UHD_Media_Tool/media_automation_requirements_architecture_v0.7.md

媒体自动化平台

需求与技术架构说明书 v0.7

编制日期：2026-09-27
文档状态：内部使用、Agent 自动化优先的需求基线；2026-09-27 17:04（北京时间）补充 MP 刮削与转移入库优先参考范围，实现与技术选型仍须通过验证。
项目名称：暂定，不构成最终品牌命名。

内部使用、Agent 自动化优先的媒体整理入库平台：用户交付目标与偏好，Agent 持续规划、调用工具、核验和处理例外，持久任务与业务服务可靠执行下载、整理、入库及维护。

本文件以本次对话最后确认的需求为准。已确认产品行为、配置示例、技术候选与待核验事项分别标识。技术方向为 TypeScript + 最新稳定版 Deno（部署固定版本）+ PostgreSQL + Pi；OpenWorkflow 是优先验证的执行引擎候选，通过兼容性和恢复验证即可纳入第一版，不必先自研执行引擎。此方向不是已经完成兼容性验证或锁定生产依赖。90% 停止下载、85% 恢复、保留 1–7 天等数值均为可配置示例，不是固定部署参数。

本次核对了 MoviePilot、MovieClaw、Pi、OpenWorkflow、Playwright、camofox-browser、Camoufox 和 linuxserver/chrome 的项目仓库及文档。未连接用户 PT 账号、下载器或实际媒体库，未部署验证这些组件的组合。后续已对照 MoviePilot V3 提交 33da9ce65d5020a8e087584a3321c1ff353c1921 与 MovieClaw main 提交 fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90 的源码；这仍非运行验证或已锁定的生产依赖版本；正式开发必须固定版本、提交和依赖清单。

当前确认摘要

主题	当前确认基线
运行时与执行引擎	优先最新稳定版 Deno，部署锁版本；优先验证 OpenWorkflow，不以自研失败作为引入前提
版本收藏	在相应作品范围内尽量保留优质 1080p、4K 蓝光二次压制双版本；同分辨率下合格蓝光压制优于 WEB-DL，特殊差异交给 Agent
自动发现	明确条件与 Agent 主动选片同时运行；未命中规则不同于明确禁止，均通过统一去重、质量和预算检查
偏好界面	一个偏好一个可编辑标签；区分软偏好/硬规则、作用范围、来源，手动取消不能被 Agent 反复加回
空间与优先级	显式即时任务 > 追更/补缺 > 新作品 > 升级；缓存硬阈值、恢复水位和在途空间预留可配置
Agent 授权与交互	授权内边执行边汇报；只规划指令不执行；可受用户委托调查整个 qB，标签只限定日常自动纳管范围
旧库与人工纠错	先只读扫描建映射，不改路径；人工纠错在适当节目/季/来源范围内持续生效，自动刷新不得覆盖
综艺与跨季	正片覆盖必须齐，附加内容按节目配置；TMDB + 本地模糊召回 + Agent 兜底，控制误关联及待识别积压
站点快照	站点独立启停，周期快照、缓存优先，未命中再实时搜索；执行前复核易变信息
PT 站点工作台	统一格式浏览/搜索/操作，关联本地库存与任务；原站视图支持人工接管与 Agent 协作；优先接入已有 camofox-browser
媒体服务器	可选 Emby 兼容查询，辅助判断有无、完整度和版本；整理记录经 API Key 接口供外部适配
Agent 设置	上游/模型、思考档位、上下文预算、压缩和子代理开关；首期不做轻重模型分档路由
下载无进展	默认不自动换源；用户手动搜索或明确委托 Agent 执行，原任务处置单独判断
用户与实例	单管理员、全局策略；多个 qB、多个 Emby 兼容实例；API Key 分别签发、撤销与限权
MP 对标	多文件、整季包、目标冲突及中断恢复以 MP 实际业务实现为主要参考，具体行为仍需源码和实例核验

正文已同步修订，不仅追加变更摘要。原十轮决定仍保留为背景，下文新增确认对较早的默认建议具有优先级。

原十轮确认结果（保留）

回合	已确认决定	产品结果
1	覆盖下载入库、持续维护和媒体管理	定位为长期媒体管理中心
2	支持媒体级整理、搬运与改目录	可主动重新命名和调整所选媒体；整库迁移、底层物理盘调度暂不做
3	分操作授权，整体偏自动化	启用规则即持续授权范围内动作，人工处理例外，不逐次审批正常下载
4	Agent 默认自行调查并据证据继续执行；经授权可优化规则	规则优化支持限定节目/来源范围、样本回放、版本与回滚
5	确定性条件和 Agent 偏好选片都支持	每条策略配置判断方式、预算、执行权限；保留选片理由
6	单次收录和持续追踪都支持	剧集默认持续追踪、补缺；追新季和停止条件可配置
7	按库/目录配置登记或接管，作品可覆盖	首次接入预览影响，启用后持续维护
8	Copy/Move 入库；Copy 源文件按缓存空间与保留要求清理	Move 成功结束下载侧管理；Copy 保留源文件做种，满足条件才清理
9	待处理中心 + Agent 先排障	支持账号密码、Cookie、API Key 与浏览器辅助恢复；消息渠道未确定为必需
10	完整控制台与 Agent 双入口	两边共用配置、任务和状态，默认首页呈现运行情况与待处理

此前已确认的范围： 主力站点为观众、HHClub（用户称 HHWEB，暂按憨憨解释）、CHD、馒头；主要接入约 5–6 站，其他站点待定。qB 通过可配置管理标签纳入自动化。双版本、综艺等待/替换方式、收录条件均为可配置策略，不固定为两种预设版本。

边界： Move 的 H&R 处置、清理候选排序、阈值与单位是待配置/验证的执行细节；不能把尚未明确的默认值当成用户已授权行为。整库迁移、分支盘均衡不属于首期。后续原型可改变技术候选，不能改变上述产品要求。

阅读导航

01 产品定位与范围 · 02 已确认需求与硬约束 · 03 核心概念与总流程
04 多 RSS、PT 观察与站点工作台 · 05 国产综艺与非标准集数 · 06 双版本与自动收录
07 稳定路径与元数据 · 08 定期校验与恢复 · 09 技术架构选择
10 Pi Agent 接入 · 11 工作流与一致性 · 12 数据模型与接口
13 界面、安全与运维 · 14 借鉴方式及许可边界 · 15 实施阶段
16 验收场景与指标 · 17 待落实事项 · 附录 参考来源

01 产品定位与范围

1.1 要解决的问题

这不是给传统下载工具加一个聊天窗口，而是面向已有媒体库的自动化管理程序。系统持续接收 RSS、站点列表、搜索结果和本地文件等观察，回答四个问题：资源是什么、用户是否需要、应该满足哪个版本目标、执行后是否真的成功。

优先解决的真实问题包括：国产综艺正片与附加内容命名混杂；TMDB 集数与译名更新影响追更和入库；多个版本不能相互覆盖；多个 RSS 和 PT 的重复发现；站点访问需要浏览器；已有目录不能因识别和刮削反复变化。

产品同时提供传统管理界面与上下文 Agent。常规流程在模型服务不可用时继续运行；无法确定的对象暂存并进入待处理中心，不为了“自动化完成率”强行猜测。

1.1.1 内部使用与 Agent 自动化优先

产品服务于用户自己的媒体基础设施，以单管理员内部部署为首期定位。Agent 是主要任务委托和自主处理入口，控制台提供完整的可视状态、配置、人工修正和接管。内部部署不要求公网开放：文中的“公开 API/MCP”指文档化、可供授权调用的产品能力，不等于向互联网匿名开放。

Agent 接受目标并在权限内完成“调查 → 规划 → 执行 → 核验 → 持续跟踪”。后台站点事件、下载完成、识别歧义及定时检查也可主动触发有界 Agent 任务，无需用户保持聊天或反复催促。确定性路径直接执行，只有需要推理的节点调用模型；这同样属于 Agent 自动化优先，而不是要求每次复制、轮询都消耗一次模型调用。

内部使用降低的是多租户、通用发行和开放插件生态的投入；文件核验、恢复、凭据隔离及明确授权仍然保留。许可条款按实际用途和拟用代码核验，不能把“内部使用”自动解释为所有许可约束都不适用。

1.2 首个可用版本的边界

首先支持电影、电视剧和国产综艺，接入 qBittorrent、多 RSS 和四个主力 PT：观众、HHClub、CHD、馒头，以及可选的 Emby 兼容库存查询。整理记录通过 API Key 接口供外部程序适配，核心不要求内置媒体服务器刷新、播放记录或收藏同步。完整控制台和内置 Pi Agent 同时作为正式管理入口，API/MCP 为产品公开能力，内置 Agent 也通过这些能力管理系统。

支持在既有媒体目录中登记库存、追踪缺口与版本、辅助元数据维护；支持用户主动发起的媒体级重命名、目录调整与搬运，行为范围参考 MoviePilot。整库迁移、跨服务器整体搬迁、mergerfs 底层盘调度与空间均衡暂不做。

下载后主要使用 Copy 或 Move 入库。Copy 的下载缓存清理由空间阈值、已入库状态和 H&R/配置保留要求共同控制；Move 成功收尾后结束下载侧生命周期。浏览器访问、凭证管理、人工接管属于核心站点能力，需要进入早期验证。新增 PT 站点工作台，提供结构化整理视图与真实原站视图；优先接入用户已有 camofox-browser，支持后续随部署提供独立浏览器服务。具体同会话画面接管方案尚待验证。

首期为单管理员和全局收藏策略，支持多个 qB 与多个 Emby 兼容实例；API Key 可分别签发、撤销和限制能力范围。不建设多人独立偏好、组织审批或租户配额。

不重写 BitTorrent、播放器或转码平台。首期不做音乐、照片、开放插件商店、多租户 SaaS、可视化工作流编程平台，或让 Agent 自行修改生产代码。

02 已确认需求与硬约束

编号	已确认需求	系统必须提供的结果
R01	多个 RSS 并存	同站或跨站 Feed 可独立配置，统一观察、去重、追踪来源
R02	国产综艺默认正片齐全，附加内容可选	区分正片、分段、加更、花絮等，支持按节目全部收录
R03	TMDB 滞后不阻断	本地可建立临时节目/集对象，后续补充映射而非推倒重建
R04	按规则收录双版本	独立收录目标、缺口、升级和完成状态，版本互不挤占
R05	根据 PT 每日新增自动收录	资源发现驱动规则，不必每部作品预先手动订阅
R06	部分 PT 需要浏览器	受控浏览器访问、登录态管理、限流、人工接管
R07	保持最终路径结构	接受现有目录；外部译名、年份及 ID 变化不触发改名
R08	不绑定 TMDB 身份	本地实体为主键，外部 ID 与资产位置分别映射
R09	数据库存映射并定期校验	可核对身份、元数据、文件、版本目标与媒体服务器状态
R10	必要时 Agent 辅助刮削	补全、解释、冲突处理均有证据与授权范围，授权内可自动执行
R11	以 MoviePilot/MovieClaw 具体实现为基线迁移适配	参考调用链、分支、状态、数据结构与恢复逻辑，迁移为 TS；记录来源及差异，用于内部系统
R12	Pi Agent 作为优先候选	使用成熟推理内核，不自研模型调用循环
R13	自身公开 API/MCP，供内置及外部 Agent 调用	与界面共用业务合同、授权、审计和任务状态
R14	qB 标签管理	自动任务打标签；已有任务贴标签后可接管；数据库维护业务映射
R15	Copy/Move 与下载缓存清理	入库验证、做种要求、空间阈值和源文件清理有明确状态
R16	条件选片与 Agent 偏好选片	规则驱动或主观判断都可配置，决定可解释
R17	自动执行为主、按操作授权	正常流程不反复请求确认，异常任务独立进入待处理
R18	旧库分范围接管	库/目录默认配置、作品覆盖，启用前预览影响
R19	控制台与 Agent 双入口	主要管理操作两边可达，共用事实与任务；凭证及浏览器本人验证用专用界面完成

补充需求编号

编号	已确认需求	系统必须提供的结果
R20	偏好标签编辑与学习	软偏好与硬规则分开；来源/范围可见；手动取消可持续生效
R21	下载缓存硬阈值	阻止新下载并暂停范围内在途任务；保留做种和整理；低水位恢复
R22	跨季综合召回	TMDB、本地别名/模糊搜索与 Agent 配合；已观察资源可找回，候选不污染正式库
R23	整理记录公开接口	API Key 鉴权、文件级前后路径、状态、时间、失败原因与增量读取
R24	Emby 兼容辅助查询	多实例查询有无/季集/版本；未知不当缺失，库存证据不等于纳管授权
R25	站点缓存优先	独立启停、周期快照、实时补查、易变字段复核
R26	Pi 原生能力配置	上游、模型、思考、上下文、压缩和子代理；不预设模型档位路由
R27	禁止默认自动换源	异常可自动调查，换源由手动选择或用户明确委托
R28	单管理员、多服务实例	全局策略；独立 API Key 和实例路径映射
R29	交互执行模式	授权内边执行边汇报，可纠正/停止；只规划指令不产生执行副作用
R30	PT 站点工作台	统一浏览、搜索、详情与下载入口；标注库存/版本缺口/下载状态，共用站点快照
R31	同会话原站接管	人与 Agent 可交接真实浏览器会话；人工操作时自动化让出控制，恢复时重新读取页面
R32	可配置浏览器后端	优先接入现有 camofox-browser；接口封装、站点账号隔离；不强制 Chrome 与 Firefox 串联

2.1 不允许被后续实现破坏的原则

身份不等于名字，路径不等于外部 ID。 内部业务关联使用本地 UUID。TMDB、IMDb、TVDB 等只是带来源、类型与历史的外部映射；文件位置属于资产，不是作品主键。

已经建立的路径绑定不随元数据重新计算。 新一集或新版本应优先使用数据库保存的作品、季和库路径绑定，不得因新译名另建第二个作品目录。新目录首次创建才按现有模板分配，之后固定。显式迁移是另一项操作。

模型不能成为业务事实的唯一来源。 模型据证据判断并通过工具执行；业务服务校验权限、前置条件和结果后提交。授权内不要求人工重新确认每个模型判断。没有证据的字段可以为空，模型的自报置信度不能直接当真实概率。

失败不等于不存在。 元数据接口超时、站点登录失效、NFS/FUSE 挂载断开，不得解释为作品删除、文件丢失或需要重新下载。

清理按明确授权自动执行。 本版支持已授权的下载缓存清理；任务必须已验证入库并满足保留要求。媒体库旧版本的处置由独立策略控制，不能因 qB 任务删除而连带删除媒体库文件。仅凭标签、模型判断或单次缺失观察不构成删除授权。

03 核心概念与总流程

3.1 统一术语

概念	含义	不能混为一谈的对象
Site / SiteAccount	站点及用户授权账号，承载访问预算和凭证引用	一个站可以有多个 Feed
FeedSource	RSS、Atom、列表或定向查询的持续观察入口	不是“我想追某部剧”的订阅
Observation	一次有来源与时间的原始观察	不是已经确认的事实
SourceRelease	某站发布的一条资源及其状态	不是作品，也不是下载后的文件
MediaEntity / ContentUnit	本地作品、季、集或节目内容单元	不以外部 ID 或集号作唯一身份
ExternalIdentity	本地对象与外部元数据对象的映射	不是目录名称
MediaAsset / AssetLocation	文件资产及其一个或多个位置	一个文件可能有硬链接等多处位置
Subscription	用户长期追踪的作品或内容目标	不等同于 RSS URL
AcquisitionPolicy / Slot	收录条件与独立版本目标	Slot 不等同于导演剪辑版等内容版本
Task / Artifact / Approval	工作单、证据/计划产物、授权记录	不依赖聊天历史充当账本

3.2 主流程

flowchart TD
  A["RSS / API / HTTP / 浏览器 / 本地扫描"] --> B["原始观察与去重"]
  B --> C["本地身份与内容覆盖"]
  C --> D["规则 / Agent 选片与版本目标"]
  D --> E["授权、预算与空间检查"]
  E --> F["下载与文件核验"]
  F --> G["按路径绑定整理入库"]
  G --> H["整理记录与库存核对"]
  H --> I["保留、清理与定期对账"]

Pi Agent 接受并维护用户目标，按需协调搜索、识别、选片、下载、整理和异常恢复；同时可被后台事件唤醒处理歧义与自主发现。已确定的流程交给持久任务执行，不串行拦截每条正常 RSS。用户通过聊天与表单修改规则时，最终都调用相同业务接口。

这里的 Media Graph 指关系模型，并不意味着采用图数据库。首版由 PostgreSQL 关系表与必要的 JSONB 证据记录实现。

04 多 RSS、PT 观察与站点工作台

4.1 Feed 的身份及配置

一个站点可以有电影、剧集、综艺、促销、搜索结果等多个 Feed。每个 Feed 记录用途、站点账号、解析器版本、轮询策略、过滤范围、游标、最后成功时间和健康状态。Feed 可用于发现、定向追踪或促销信号；内容是否下载由收录策略决定。

同一站点所有 Feed、搜索和浏览器操作共享站点级访问预算。轮询间隔首先满足站点规则与响应限制，再结合更新频率和 Feed 容量调整；不把“每分钟抓一次”当默认承诺。

凭证采用 secret reference。含 passkey 的 URL 不进入日志、模型上下文、公开导出或报错信息。XML 解析禁用外部实体并限制响应大小、解压量及条目数。

4.2 多层去重

来源条目首先按 Feed 的 GUID 与内容摘要处理更新；同站资源优先用站点资源 ID 聚合。一个资源可以保留多条 observed_by，不能因三个 Feed 都发现它而下三次。

跨站使用 infohash、文件清单、体积及发布特征关联，但不能把“同一作品”当成“相同种子”。相同电影的 REMUX 与 WEB-DL 是不同候选；相同字节在不同站的促销、做种规则和下载入口也要分别保留。

多站转载可能来自同一发布源，不构成多份独立证据。节目存在性或身份判定需保留上游来源关联，不使用“出现两次，所以可信度翻倍”的规则。

4.3 增量、漏项与补偿

保存 first_seen_at、last_seen_at、source_published_at 和 fetched_at，避免混淆“今天发现”和“今天发行”。Feed 抓取采用重叠窗口与持久去重，不只依赖最后一个递增 ID；条目更新、置顶、补种和乱序都应可处理。

RSS 通常不是完整历史账本。系统检测停更、抓取中断或窗口可能被覆盖后，创建有预算的列表/搜索补漏任务。若缺少权威对照，只显示“疑似缺口”，不展示无法计算的精准遗漏率。

支持 ETag / Last-Modified 条件请求（来源支持时）、退避、Retry-After、熔断和手动恢复。仅 Feed 消失不能推断站内资源已删除；促销状态应有 observed_at 与 expires_at，真正下单前按策略复核。

4.4 浏览器访问与 Agent 排障

Adapter 按动作选择 API、RSS、HTTP 或浏览器。程序允许用户保存账号密码、Cookie 或站点 API Key。常规请求失败时，在既有授权下自动诊断并按策略切换浏览器；Agent 可结合 DOM、截图和受控交互执行登录、检查会话与定位问题。凭证由服务端按需注入指定站点登录字段，不进入模型上下文。

按站点与账号隔离登录状态，对同一 profile 串行加锁。导航有域名范围、超时、重试和资源预算；浏览器没有媒体库写权限。浏览器可以处理正常页面交互与会话恢复，但不承诺通过所有 Cloudflare 挑战；验证码、二次认证或本人设备确认不能完成时，进入待处理并提供浏览器接管入口，不无限重试。

认证状态可能包含 Cookie 与其他敏感存储；不能把“一次保存 cookies”当成永久登录保证，sessionStorage 等需按真实站点验证。[S09] 页面解析优先使用已验证提取器。Agent 可提出修复建议，提取逻辑变更经样本回放及对应授权发布；首期不自动修改生产 Adapter 代码。

4.5 四站接入与通用边界

站点	当前参考源码路径	本项目做法
观众	MovieClaw audiences.yaml，NexusPHP	共享 HTTP/认证/解析底座，配置列表、副标题和分页
HHClub（待最终确认用户所称 HHWEB）	hhanclub.yaml，NexusPHP 定制卡片	专门的列表/详情/促销选择器；发布组偏好与站点身份分开
CHD	chdbits.yaml，NexusPHP	配置分页、分类、促销期限与登录验证
馒头	mteam.yaml + custom/mteam.py，API	优先 API Key，按资源 ID 获取详情和下载令牌

以上仅为所读源码的适配方式，不是当前账号实测。原始分类 ID、标签、副标题必须保留，不能将综艺等不可逆地压成 tv。首期采用随产品发布的 Adapter 注册表，常见差异用配置，特殊逻辑用专用模块。先做观众和馒头两类链路，再扩到其余主力站点；不为首批站点建设插件市场。

4.6 站点快照、缓存与启停

每个站点可独立开启/关闭。开启后按可配置周期同步列表/资源快照，记录抓取时间、覆盖范围、游标、来源健康和字段新鲜度。保留原始标题、分类、副标题与资源标识；不将一次分页抓取伪称全站快照。

搜索首先查询本地资源索引与快照。没有候选、候选不能满足目标，或覆盖/新鲜度不足时，对已开启站点实时补查；并发相同搜索合并，失败采用退避。站点级限流对快照、实时搜索和浏览器统一生效。缓存命中不代表其中包含所有最新资源，也不能替代下载前对令牌、免费期限、HR 等易变信息的必要复核。

关闭站点即停止其网络访问及新下载候选执行；历史资源仍可查并标注关闭/过期状态。该站已在 qB 的任务仍按原下载与保留策略管理。缓存保留期、快照频率、实时补查新鲜度属于可配置值，待真实站点验证后给默认值。

4.7 PT 站点工作台（已确认新增功能）

目标是让用户在程序内查看、搜索和操作已授权的 PT 站点，后台自动化与人工查看可以围绕同一资源、同一站点会话协作。不是仅提供浏览器跳转链接，也不是让 Agent 每次用视觉从头阅读整个网站。

4.7.1 两种视图

视图	用户可见能力	数据与执行来源
整理视图	统一资源列表、分类、筛选、搜索、详情；展示免费状态、做种人数等可获取字段	站点快照优先，API/HTTP 或浏览器按需补充，标注来源和更新时间
业务叠加信息	已收藏、已有版本、缺少 4K、正在下载、匹配偏好与候选理由	本地身份/Slot/任务与 Emby 辅助库存，不从网页标题直接猜出确定事实
原站视图	真实浏览器页面、点击/输入/查看特殊详情，必要时人工登录或处理验证	当前后端浏览器会话的画面与输入通道，具体传输方案待验证
Agent 协作	解释当前资源、调查访问失败、执行受委托的站点操作，并交还控制权	统一业务能力与浏览器会话管理，不另建独立下载和授权链

“格式化”采用提取字段后由本系统组件渲染。四个主力站的常见列表和详情用固定适配器；未适配结构、页面变化与特殊详情再由 Agent 辅助处理。不直接将站点原始 HTML/脚本注入产品页面，也不承诺复刻论坛、发帖、交易等全部站内功能。

整理视图点击下载时仍通过原有计划、去重、缓存硬阈值、实例选择和管理标签流程。若浏览器捕获到 .torrent 等下载产物，应交给后端受控暂存与核验，再进入同一提交能力；浏览器本身不获得媒体库写权限。具体下载捕获接口需对选定版本验证。

典型流程：打开观众 → 从缓存浏览资源 → 看到“已有 1080p、缺 4K” → 查看最新详情 → 手动下载或委托 Agent 判断 → 正常提交 qB。页面提取失败时保留既有数据并标过期，可切换原站视图或进入待处理中心，不展示空列表冒充站点没有内容。

4.7.2 浏览器服务选型与可插拔边界

优先连接用户已经运行的 camofox-browser，配置服务地址与凭据；后续允许随部署启用独立浏览器容器。业务应用通过自有 BrowserProvider 合同访问浏览器，建议涵盖会话/标签页、导航、快照、截图、交互、提取、下载产物和接管能力声明。此为本项目接口设计，不声称上游全部具备同名接口。

camofox-browser 是以 Camoufox/Firefox 为基础的自动化服务，项目文档列出页面快照、截图、结构化提取与下载捕获等能力。[S18] linuxserver/chrome 提供通过 Selkies 访问真实 Chrome 画面的方案，适合参考其远程交互方式，但不是 camofox-browser 的显示前端。[S19]

不得将“用户看 Chrome、Agent 操作另一个 Firefox”标为同会话协作，也不假定复制 Cookie 就能完整迁移登录/验证状态。若保留独立 Chrome 作为额外工具，必须明确标注独立会话。首选研究给同一 Camoufox 实例增加可视化接管：其底层有虚拟显示运行能力，但 camofox-browser 封装、画面传输和输入接入仍需原型验证。[S20]

浏览器后端独立运行，不要求其依赖全部移植为 Deno；Deno 业务服务经受控接口调用。API 能稳定完成的动作继续走 API；常见解析不强制消耗模型。浏览器并发、空闲释放、启动延迟和内存按四站实测设置，不采用宣传数字作为项目性能承诺，也不承诺通过所有反爬挑战。

4.7.3 会话控制与交接

会话按站点/账号绑定，控制权至少区分自动化、人工接管、等待处理与关闭。接管前停止该会话新的自动化输入，确认当前操作停止或收尾后交出控制权；其他无关会话可继续。界面显示当前操作者、站点、页面与连接状态。

人工操作结束后，Agent 重新读取页面和登录状态，不复用跳转前失效的元素引用或直接重放上次点击。人工已完成的动作要先核对结果再恢复流程，尤其避免重复提交下载。接管中网络断开、任务取消或服务重启时保留可恢复状态，不自动从未知页面继续点击。

原站画面与输入通道沿用产品认证，后端控制接口不作为公开裸接口。敏感登录界面由用户或凭证代理处理；截图/快照进入模型前按场景遮蔽凭据。账号退出、凭据更换与站点关闭应使相关自动访问停止，历史快照仍按既定策略保留。人工接管不是对其他站点、宿主终端或文件系统的全局授权。

4.7.4 原型验证要求

先固定用户现有 camofox-browser 的仓库、版本、启动方式及认证配置，再核对真实 API，避免把不同 fork 的能力混用。验证登录保持、截图/结构化快照、列表/详情提取、文件下载捕获、重启后会话行为，并验证人工与 Agent 能否在同一标签页连续操作。

四站分别测试常规访问、登录过期、页面变化、需人工验证和服务不可用；未通过的能力在界面明确标为不可用，不能用另一浏览器窗口代替后宣称同会话验证成功。性能测试记录缓存命中延迟、实时查询延迟、并发资源占用与失败恢复时间。

05 国产综艺与非标准集数

5.1 内容分类与集号分开建模

解析输出至少包含：节目/播出周期、本地内容单元、来源期号、播出日期、内容类型、分段、候选关联和证据。来源标题中的 EP10、第十期、20260927 不应直接等同为同一外部 SxxExx。

建议内容类型包括 main、extra、behind_the_scenes、performance_only、preview、reaction 和 unknown；segment 可为 full、upper、middle、lower 或未知。正片与画质是两个维度；“会员版”“加长版”“纯享版”不能跨节目统一写入黑名单。

“只收正片”指内容覆盖目标：可以由一个完整正片文件满足，也可以由上下两段共同满足。是否等待完整版、是否接受分段、完整版出现后是否替换分段，由节目策略明确，不能把用户原意缩窄为“必须只有一个文件”。

5.2 分层识别流程

先运行标题规则、来源结构化字段及已验证的节目专属规则；仍有歧义才获取详情或调用 Pi。下载前常常拿不到真实时长，系统必须区分“缺字段”和“字段不满足”。下载后再通过 ffprobe/MediaInfo 复核实际媒体属性。

同一期候选可以进行相对比较，但片长最长不等于正片，完整版也不必然等于上下两段无损合并。节目官方介绍、来源描述、节目历史结构和文件清单应共同构成证据；不充分时保留未知。

例如某期出现“上”“下”“会员加更”“完整版”，系统先建立候选覆盖关系，而不是立即把四条资源塞入同一个 episode 文件。确认完整版覆盖所需正片之后，才把该版本目标判定为完整。

5.3 规则学习与安全发布

用户纠错形成带节目、来源、播出周期和规则版本的标注样本。Agent 提出规则修订，系统回放历史正反样本，展示新增命中与误排除，在授权范围内发布，或请求用户确认。默认 Agent 可调查和应用现有规则；自动修改长期规则需要额外授权，可限定节目、来源、预算与有效期。一次纠错不能直接推导出适用于所有综艺的全局规则。

识别结果保留 evidence_ids、规则版本、模型版本、拒绝原因和质量档位。只有通过实际标注集校准后才允许展示概率；初期使用“规则确认 / 多证据支持 / 需确认”等证据等级。

评估集至少覆盖多个节目、不同站点、不同播出周期、简称改名、会员正片、分段与日期编号。按节目及来源分组划分测试集，避免同一命名模板泄漏导致虚高准确率。

人工纠错的持续效力

前端可修改作品、季、期、正片/上/下/加更等对应关系，对话调用同一接口。用户纠正立即成为当前对象的正式映射，并在合适的节目、季和来源范围内形成可追踪的规则或样本；不自动推广至全部综艺。人工确认有锁定与修订历史，后续元数据刷新不能覆盖。修正先更新数据库关系，文件改名或搬运另受目录整理策略约束。

这类显式纠正本身就是相应范围的授权，无需再按“Agent 自主修改长期规则”重复请求确认；超出本次纠正范围的推广仍遵循授权与回放规则。

5.4 本地集账本

ContentUnit 使用稳定本地 ID，展示序号、播出日期、来源编号和外部映射可修订。TMDB 未更新时，可创建 provisional 单元并继续观察、下载和按策略入库；“已发现”不等于“已入库”。

区分观察状态、身份状态、下载状态、资产状态及 Slot 满足状态。总集数未知时保持追更，不因当前已知集数齐全就结束订阅。后续 TMDB 改编号或将上/下拆分时更新映射，允许一对多/多对一的编号关系，不重命名旧文件。

对媒体服务器无法表达的临时编号，不伪造外部 ID。可采用明确批准的本地 NFO/编号投影，或保持已入库但元数据待同步；播放器识别结果必须独立验收。

5.5 正片与附加内容的默认完整性

默认正片必须齐：上/下共同满足一期，缺少任何必要分段继续追踪；已确认覆盖完整正片的合并版可满足同一目标，无需为凑齐名称重复下载。加更、花絮、纯享等单独分类，默认不影响正片完整性，按节目偏好决定是否收录；支持“此节目全部收录”标签。会员/加长版需判断是正片扩展还是独立内容，歧义交给 Agent。

完整性针对启用的每个 Slot 分别计算。电影的蓝光压制双版本偏好不能未经配置扩展成所有综艺的默认要求，综艺可使用独立 WEB-DL、分辨率与版本策略。

06 双版本、升级与自动收录

6.1 使用独立收录目标，而非一条质量排名

每部作品或内容单元可有多个 Slot，例如 archival 与 streaming。这只是示例命名；真实规则由用户配置。每个 Slot 定义硬条件、软偏好、回退条件、预算、升级阈值和完成条件。

将内容版本与交付版本分开：院线版/导演剪辑版描述内容差异；分辨率、编码、音轨、字幕、REMUX/WEB-DL 描述交付特征；Slot 描述用户要维持的目标。三者不可共用一个 edition 字段。

规则层	示例	行为
硬条件	指定内容版本、必需字幕、体积上限	已知不满足则拒绝；未知按单独策略处理
软偏好	优先 DV、某发布组或较低体积	硬条件通过后排序
回退	指定等待期后接受次选来源	保留尚未满足最终目标的状态
升级	达到最小改进、避免相同等级反复更换	创建替换计划，不直接覆盖旧文件
组合	两个不同物理版本必须同时存在	显式 require_distinct_asset，不默认一份文件算两份

某文件满足两个规则不必复制两份；但用户要求真正的双版本时，必须有两个不同资产或经确认的不同版本内容。每个 Slot 分别显示 empty、reserved、downloading、verifying、satisfied、upgrade_pending 或 attention。

当前确认的收藏偏好

用户偏好在适用作品范围内尽量保留质量合格的 1080p 与 4K 蓝光二次压制，作为两个独立目标各自升级。已有 4K WEB-DL，出现合格 4K 蓝光压制时优先后者；只有 WEB-DL 时可先收录并继续追踪。低劣压制不会仅因 BluRay 标签更优就自动替换。蓝光二次压制（Encode）不等于原盘或 Remux，不默认“越大越优先”。

音轨、字幕、特殊剪辑、实际压制质量等边界交给 Agent 综合证据处理；不要求用户预先穷举全部例外。调查和判断不扩大文件删除权限。新版本验证通过前保留旧版，旧媒体何时删除或保留多长时间仍按独立策略配置，不能将本段偏好解读为授权立即永久删除。

6.2 电影与剧集的完整性

电影目标按内容版本核对。剧集和综艺目标按内容单元与分段覆盖核对，不能因下载一个 season pack 就声称整季完整。合集必须检查实际文件清单和所覆盖单元；单集、合集或跨站重复均进入同一满足度计算。

上一个版本仍可用时，升级先下载并验证新文件，再切换 Slot 的当前资产；旧文件只在满足已授权的媒体保留策略后处理；下载源的做种保留与缓存清理另外判断。不能因为更高分候选出现就提前删除旧文件。

6.3 “每日新资源”拆成三个明确模式

新作品收录： 依据作品发行/播出信息识别新作品，站点今天上传旧电影不自动变成新片。

追更补齐： 依据本地集账本检查新内容单元和缺失分段；不要求 TMDB 已列出该集。

已有作品升级： 依据当前 Slot 缺口及升级条件处理新发布版本，独立于作品上映日期。

三者均由 Feed 和站点观察触发，支持每日汇总，但采集频率不能仅“一天一次”而漏掉有限 Feed 窗口。评分、国家、类型、字幕等条件均可配置，未知评分不应未经用户授权自动排除新片。

6.4 计划与预算

自动收录必须有每日新增作品数、下载字节、站点比例风险、存储保留量和并发限制。预留下载计划时一并预留 Slot 与预算，避免多个 Feed 并发抢占同一目标。

策略编辑采用草案、历史预览、授权发布、版本化和回滚。启用策略即授权其范围内的持续操作，不逐次审批正常下载、追更或整理；升级、媒体清理、下载缓存清理可分别授权。自然语言只生成结构化策略数据，不生成可直接执行的 JavaScript；这些数据不是另一套工作流 DSL。业务排序与硬约束均由代码执行，Agent 解释结果而不临场更改分数。

6.5 选片方式与追踪方式

每条收录策略可使用明确条件、Agent 自然语言偏好判断，或两者组合。明确条件由代码执行；Agent 挑选需记录证据与理由，并遵守独立预算和权限。模型不可因主观偏好放宽站点、空间或做种硬限制。

策略可选择单次收录或持续追踪。用户主动添加的剧集/综艺默认持续追踪并接续后续季；明确“只要这一季”则收窄为本季补齐及配置内升级。Agent 自主推荐收录默认追完当前季，不自动接续下一季。前端提供“仅本季/持续后续季”，可随时修改。特别篇、衍生节目和同名重启不直接视作下一季，按证据识别，歧义交给 Agent。已建立追踪不因评分改变自动终止。Agent 的“作品值得收录”与“资源是否属于该作品/正片”分开记录与验证。

确定性条件与 Agent 主动发现可同时运行：命中明确条件的自动收录；未命中但无明确排除的作品，由 Agent 在授权预算内挑选。明确禁止项不得被推荐突破。已有作品转入补缺/升级检查，两条路径共享质量、去重、空间和权限检查。

6.6 现有库接管

按库、目录配置只登记或自动维护，作品级配置可覆盖。首次接入展示预计影响的作品、版本缺口和下载量；无法可靠估算的项目标未知。用户启用后按预算持续补齐与升级。只登记范围可查询库存与缺口，但不能由新全局规则隐式升级成自动下载。

首次扫描自动识别并登记，高证据强度结果可直接建映射；模糊项由 Agent 深入调查，仍未解决则进待处理中心。首次接入不改现有文件名、路径，也不隐式开启升级与整理。

6.7 前端可编辑偏好标签

一个偏好显示为一个标签，可添加、编辑、停用、删除，通过对话修改与前端操作等价。详情包含软偏好/硬规则类型、作用范围、来源（手动/对话确认/Agent 推断）、说明、修订与生效状态。标签是结构化偏好的展示，不把所有业务语义压成自由文本 tag；复杂条件放详情中。

“偏爱科幻”影响排序，“不收恐怖片”是硬排除，“优先蓝光压制”是版本偏好，“1080p + 4K”是独立目标配置。用户说“以后都这样”可形成长期偏好；“这次不要”只影响当前项。重复反馈可调整软排序并显示原因，永久硬规则需要明确依据或既有授权。删除文件不直接推断讨厌作品。

手动取消标签必须留有取消/抑制记录，Agent 不得下一轮根据同一旧证据自动加回；用户重新启用或明确授权后方可恢复。人工纠正与偏好调整均可查历史。

6.8 任务优先级

默认：用户明确立即处理的任务 → 正在追踪的更新/补缺 → 新作品收录 → 已有版本升级。优先级可配置，只影响资源分配，不越过磁盘硬阈值、HR 或权限。Agent 自主选片预算可独立控制，防止挤占明确追更任务；同优先级排队与防饥饿细节待执行器验证。

07 稳定路径、身份映射与元数据

7.1 保持现有目录，不再设计新目录规范

本项目不强制 /tmdb-123、/UUID、archival/streaming 子目录，也不引入会随译名变化的“展示路径”。已有文件先只读登记。当前目录模板保留，新资产需要入库时沿用已绑定的作品/季目录。

数据库保存 library_root_id、relative_path、路径绑定对象、绑定时间和模板版本。实际访问位置由库根配置解析；迁移挂载点可以更新根映射，不等同于物理重命名。下载器路径、宿主路径和媒体服务器路径通过各自适配映射对齐。

关键场景： 旧目录按首次译名创建，TMDB 后来改名。界面和允许更新的 NFO 可展示新译名；新集仍进入旧目录；资产 ID、历史下载、Slot 和关联保持不变。存在两个历史目录时先建立冲突任务，不按最新标题自动合并。

7.1.1 媒体级主动整理

支持对所选作品或文件预览并执行重命名、目录调整、Copy/Move 搬运，具体行为对照 MoviePilot。它是显式媒体整理操作，与自动元数据刷新分开：前者可变更路径绑定，后者不得隐式改变目录或文件名。计划检查冲突、下载器引用、实际文件系统与可用空间，完成后更新路径映射并发布可增量获取的整理记录，由外部程序按需适配媒体服务器。整库迁移和底层分支盘调度暂不做。

7.2 外部身份映射

映射字段包括 provider、provider_entity_type、external_id、本地 entity_id、accepted/proposed/conflicted/retired 状态、证据、有效期、校验时间和人工锁。TMDB movie:123 与 tv:123 必须区分，不能只保存裸数字。

纠正误匹配时新增映射修订并保留旧历史，不直接覆盖后失去审计。已接受映射的唯一性约束应包含提供方和对象类型；有疑义的候选允许并存，但不能同时被当作已确认身份使用。

身份合并、拆分以及节目季结构调整均需事务化计划和引用检查。仅译名变化不足以触发换 ID；404、超时和鉴权失败也不是立即删除映射的依据。

7.3 字段级元数据协调

原始来源快照、候选字段和最终展示字段分开。每个最终字段保留来源、语言、时间、锁定状态与来源修订。用户锁定优先于自动刷新；Agent 翻译标注为生成内容，不伪称 TMDB 官方译名。

身份已确认后常规刮削使用 API 和缓存。只有缺失翻译、来源冲突、综艺编号、特殊剪辑版等情况交给 Pi；Pi 输出有证据的字段建议或“无法确认”，业务服务应用字段级策略。

NFO 是可选导入证据和兼容投影，不是唯一账本。写 NFO 或替换海报前要遵守用户锁，采用临时文件与安全提交；不直接改媒体容器字节，避免破坏已有做种和硬链接内容。

7.4 Emby 兼容服务作为辅助库存来源

支持可选连接多个 Emby 兼容实例，供界面、收录流程和 Agent 查询：是否已有作品、已有季集是否齐全、已有资产是什么版本。版本包括接口能提供的分辨率、编码、音轨等；WEB-DL/蓝光压制等来源类型结合文件名与已有证据判断，未知字段不强行补值。

保存 server_instance_id、server_item_id、本地关联、路径视图、观察时间、证据与匹配状态。资源完整度要与本地内容覆盖目标对照，不能仅凭服务器返回“已完结”判断。未刷新、接口失败或名称不匹配不能视为没有资源；外部库存证据也不构成文件纳管授权。已确认外部库存可以按策略满足目标，歧义库存先核对，避免重复下载。

首期不要求自动刷新媒体服务器、同步收藏/播放记录、重建媒体库或保障外部条目 ID 不变。整理前后路径和结果通过统一记录接口暴露，外部程序自行适配；外部服务同步失败不能触发重新下载或再次入库。兼容接口字段、认证和分页需在用户实际服务版本上验证。

7.5 跨季关联、模糊召回与待识别数据治理

本地 UUID 为主身份，TMDB 是辅助映射。检索尽量广，确认关联保持严格：先查人工确认、历史季关系、别名及外部 ID；再综合 TMDB 与本地标题/别名模糊索引召回。保留原名、译名、简称、年份、季号/中文序数及原始站点标题；结合主创、播出平台、发布时间和历史来源判断。搜索实现先验证 PostgreSQL 索引/模糊检索，不预设必须引入向量或独立搜索服务。

确定性证据不足或冲突时由 Agent 查证；仍不确定的资源留在可搜索的待识别池，追踪目标继续存在。TMDB 没有记录而其他证据充分时，可先建本地作品/季并正常入库，后补映射。自动模糊匹配不得覆盖人工锁定关系。

避免死数据的约束：检索候选不逐个建为正式作品；来源资源去重；失败保存原因、重试状态和证据版本；新证据到来时重试，另有有界周期复查，避免无限空跑或永久遗忘。过期候选可按保留策略归档，不能删除仍被任务/资产/人工映射引用的实体。合并重复身份保留旧 ID 跳转，维护订阅、资产、历史引用；错误合并要可修订。

区分“未发现资源”“发现但未识别”“已识别但不满足质量”“来源不可访问”。已经观察到的资源必须能由原始标题、别名或待识别入口找回；尚未观察到的资源不承诺全覆盖。验收同时报告候选召回率、确认匹配精确率、自动处理覆盖率和待识别积压，不能通过大量弃判制造虚高准确率。

08 定期校验、资产安全与恢复

8.1 五类校验任务

校验器	检查对象	自动修复边界
Identity Reconciler	外部对象存在性、类型、强交叉 ID、映射冲突	更新校验状态；换身份需计划及必要审批
Metadata Reconciler	译名、简介、图片、字段锁、来源新版本	只更新允许字段，不动路径
Asset Reconciler	文件存在性、大小、属性、位置及挂载健康	更新观察；不因单次失败删记录或补下载
Acquisition Reconciler	Slot、下载器任务、文件覆盖及预算预留	对账恢复已存在任务，释放确认失效的预留
Server Reconciler	本地资产与 Emby 兼容库存	辅助查询与映射核对，标注未知/过期；不自动重建或刷新服务器

采用事件触发与低频巡检结合。活跃追更优先，静态旧库分批扫描；周期、批量和 I/O 上限可配置。首次全库登记支持中断续扫，不能每次启动遍历全部文件。

8.2 面向大库的扫描策略

先检查挂载根哨兵、挂载状态与上次健康记录，再做分目录增量 stat。必要时读取 ffprobe/MediaInfo；只有疑似重复、替换或用户明确校验时做有预算的内容摘要或完整哈希。

inode/device 可以帮助同一文件系统内关联，但不是跨挂载、跨 FUSE 或长期持久身份。抽样摘要也不等于完整文件一致性证明。全量深度哈希不作为每日默认任务。

发现路径不存在先区分根离线、权限变化、外部移动和实际缺失。状态按 unavailable、suspected_missing、confirmed_missing 推进；确认为缺失仍需遵循恢复策略，不能绕过预算重复下载。

8.3 Copy/Move 入库与下载缓存清理

主要工作方式是下载完成后 Copy 或 Move 至最终媒体库。计划冻结目标路径、源文件、操作类型及前置条件，不能覆盖无关资产。

Copy： 写目标侧临时文件，校验并提交后登记媒体库独立副本，下载源继续留在缓存做种。下载缓存可用空间低于配置阈值时，从已验证入库且满足保留要求的任务中挑选清理对象；支持配置保留天数（例如用户举例的 1–7 天），实际 H&R 要求与用户保留时间分开判断。经过时长、累计做种时长、分享率等不能互相代替。清理到恢复阈值停止，候选排序和低/高水位是可配置实现建议，具体默认值待确认。

Move： 完成搬运、验证最终文件和数据库登记后，移除对应 qB 任务记录并结束下载侧管理。尚有 H&R 义务时不得直接搬走做种源；建议等待条件满足，或者在用户预先授权时改用 Copy，具体默认处理方式待配置。同文件系统的重命名与跨文件系统搬运不同；跨盘需要复制、验证、再删源的可恢复步骤，不能假定 rename 原子成立。[S13]

空间不足且没有可清理任务时暂停新增下载并进入待处理，不能自动突破保留要求。下载器失联、站点要求未知、入库验证未完成、路径映射冲突时，不得当作“可以清理”。qB 删除 API 的删数据选项必须基于路径引用检查：有共享保存根、未接管文件或媒体库直接做种时，不能递归误删。部分文件入库而同种其他文件未处理，不能整种按“已完成”清掉。

兼容登记既有硬链接，但不把硬链接设为本次主工作流。硬链接只在文件系统允许时使用，EXDEV 不得静默改变策略；共享 inode 时禁止原地修改媒体字节。[S12]

8.4 qB 标签接管与任务映射

管理标签名称可配置。程序提交下载时随请求打标签；用户也可给已有任务贴标签，程序发现后识别、登记并纳入管理。业务关联使用下载器实例 ID 与该实例的 torrent 标识，同时保留必要的 v1/v2 hash；标签不承载完整作品身份、Slot 或路径信息。

接管默认按已发布规则观察、识别与入库；清理、换源和 Move 依赖对应授权。标签移除后暂停后续自动动作，保留历史与媒体资产；正在执行的动作按安全边界停止或收尾，不能中途撤回已经发生的文件操作。任务消失不等于媒体资产消失。

收单超时先查询 qB 实际任务，再决定重试；发现种子原本已存在时走接管与冲突检查，不覆盖其保存路径、其他标签或文件选择。任务创建、接管、文件验证与缓存清理共享操作账本。

标签范围与用户主动委托

管理标签限定日常自动化范围，不限定用户主动委托调查的范围。“检查 qB 为什么占满磁盘”可以查询整个授权实例及未纳管任务；“暂停这些任务”可以执行此次指定操作，不必先打标签。调查不等于删除授权，一次操作不变成永久接管；“以后超阈值暂停全部下载”才形成长期实例策略，前端可见、可撤销。明确指令已经授权的动作无需重复确认。

8.4.1 磁盘硬阈值与恢复

按实际下载缓存卷配置使用率硬阈值，例如 90%。达到时停止所有收录路径提交新下载，并暂停策略范围内正在下载的任务；已完成做种、入库整理与合规清理继续。下降到独立恢复水位（例如 85%）后恢复系统因本阈值暂停的任务，不能顺带恢复用户手动暂停项。阈值不被手动优先级或 Agent 推荐绕过。

默认暂停已纳管任务；用户可以一次性指示 Agent 扩大处理范围，或授权该实例全局保护。未纳管任务也计入磁盘占用；未获授权不能自动暂停它们，因此不能声称受管任务暂停后磁盘一定不会继续增长。无法读取磁盘状态时保守阻止新增分配并告警。

下载提交需考虑现有在途任务尚需空间和并发计划预留，避免仅看当前使用率。已预分配文件与剩余需求不得重复扣算；多 qB 共用缓存卷按卷汇总。整理目标盘另做容量检查，缓存水位不替代目标盘检查。阈值、恢复水位、检查周期与统计方式在真实挂载上校验。

8.4.2 下载无进展与换源

默认不自动寻找替代资源并执行换源。超过可配置无进展时长则记录证据并汇入待处理中心，保留原任务。人工暂停、阈值暂停和正常排队不误判故障。Agent 可在日常授权内排查，但自动恢复权限不包含换源。

用户可手动搜索选资源，或明确让 Agent 排查、搜索并执行换源。换源前核对内容覆盖、质量、已有进度和站点约束；原任务暂停、移除或删数据必须由本次指令或有效策略分别覆盖。没有删除授权时保留原任务数据。

8.5 数据库备份成为核心功能

路径不携带完整身份后，数据库映射就是关键资产。需要数据库备份、映射清单导出、加密凭证备份和恢复演练。清单保存在应用数据目录，不要求往每个媒体文件夹强塞私有 sidecar。

业务表、工作流表、Pi 会话和密钥材料需有一致的恢复方案。恢复后的默认模式为只读对账，先核对下载器与真实文件，再允许自动写入。仅靠重新扫描目录不能恢复所有 Slot、审批、人工纠错和历史关系。

09 技术架构选择

9.1 推荐：TypeScript-first 模块化单体

flowchart TD
  UI["控制台 / 内置 Agent / 外部 API 与 MCP"] --> APP["统一业务能力与授权"]
  APP --> JOB["Deno worker / OpenWorkflow 候选"]
  APP --> DB["PostgreSQL 业务账本"]
  JOB --> DB
  JOB --> IO["qB / 站点 / 文件工具 / Emby 查询"]
  JOB --> BROWSER["camofox-browser / 同会话接管"]

核心部署为 console、worker、PostgreSQL，来自同一个 monorepo。浏览器可连接已有 camofox-browser 服务或单独部署，不必与主应用捆绑生命周期。浏览器是故障与权限隔离边界，不发展为一套微服务平台。主程序不默认增加 Redis、Kafka、NATS、RabbitMQ、Temporal Server 或向量数据库。

React/TanStack 负责控制台与列表交互；服务端 API 的位置与框架需通过 Deno 兼容性验证；可评估 TanStack Start 服务端路由，也可独立 Deno HTTP 入口，不预先绑定尚未验证的服务端框架。数据库访问推荐类型安全查询层加显式迁移，例如 Kysely/pg，最终依赖以兼容性验证为准。任务流程用版本化 TypeScript 代码，不自研通用 YAML/JSON 工作流语言。优先验证 OpenWorkflow + PostgreSQL，复用持久步骤、等待与恢复能力；不必先自研调度器再等其出问题。业务状态、授权和外部副作用记录仍由应用负责。若候选确有兼容性或语义缺口，再比较其他执行器或有限自研方案，不能仅凭“依赖更少”预设自研更可靠。

9.2 为什么不默认 Go 核心加 TS Agent

Go 并非不适合。它适合独立 I/O 服务或扫描工具，但本项目首要难点是规则表达、来源适配、状态一致性与 Agent 集成，而不是媒体转码吞吐。采用 TS-first 可以共享领域类型、Schema、Pi 工具、浏览器服务 Adapter 和测试数据，减少早期跨语言协议和部署成本。

文件探测与重计算优先交给 ffprobe、MediaInfo 等受控外部程序；阻塞扫描和 CPU 任务不占 Web 事件循环。只有性能剖析证明某模块不满足目标，再考虑 Go/Rust 专用工具。Python 仅为确有必要的小模型或专业算法保留可选进程，不作为默认后端。

这是工程投入判断，不是声称 TS 比 Go 快，或在未实测情况下保证任意规模都能达标。主运行时首选开发验证时的最新稳定版 Deno，镜像和部署锁定具体版本及依赖锁文件，不使用浮动 latest 自动升级。Deno 支持 npm/Node 兼容层，但这不等于 Pi、数据库驱动、MCP、浏览器及 OpenWorkflow 已联合通过。[S17] 有明确依赖障碍时可评估隔离工作进程或替代库，需记录代价，不无依据退回 Node，也不坚持所有外围进程必须由 Deno 执行。

9.3 四类状态不能互相代替

业务事实由 PostgreSQL 业务表维护；任务恢复由持久任务执行器维护；会话与压缩由 Pi Session 维护；真实文件状态由 AssetLocation 与扫描证据维护。聊天说“已下载”不是下载成功，工作流完成也不能替代资产复核。

Pi 以 SDK 嵌入，已有会话、模型、工具和资源控制接口。[S05] PostgreSQL 任务表、outbox、操作步骤与审批记录的职责需先定义；执行器选型不得使这些业务事实依附某个推理会话。OpenWorkflow 是优先验证候选；其执行状态不能替代作品/季/Slot 的业务状态。采用引擎仍要设计领域状态机，收益是少自研通用调度与恢复。不能因为 MP/MC 自研就断言它们不稳定，也不能因框架提供检查点就宣称外部操作恰好执行一次。[S07]

9.4 TS 性能边界与验证

四站采集、qB 调用和元数据请求主要受外部延迟、限流与数据库查询影响。大库容量不直接等于运行时内存需求；需记录文件数、目录数、日变化量与挂载延迟。扫描独立于 API 请求执行，控制遍历、stat、媒体探测与复制并发。大文件采用文件系统复制或流式传输，禁止将整部影片读入 JS 内存；CPU 密集处理必要时使用 worker 或外部工具。具体 Deno API 和兼容依赖通过原型验证；[S15] 仅保留为此前 Node 方案的设计参考，不代表 Deno 内部线程模型相同。

首期重点测首页/API 延迟、事件循环延迟、进程 RSS、PG 慢查询、每批扫描成本、复制吞吐和故障恢复时间。测试用实际 SSD/HDD、mergerfs/NFS 拓扑和递增文件样本。只有明确瓶颈才引入 Go/Rust 子工具，不因 PB 数值提前多语言化，也不承诺未经测试的吞吐。

10 Pi Agent 接入设计

10.1 使用 Pi SDK，而不是把编码助手原样开放给媒体库

优先使用 AgentSession 这一层，复用会话、事件流、压缩和资源接口，而不自行重写模型循环。将其包在自有 AgentRuntimePort 后，避免领域模块到处依赖 SDK 类型。

本次核对时，原 badlogic/pi-mono 链接已重定向到 earendil-works/pi，官方文档包名为 @earendil-works/pi-ai、pi-agent-core 和 pi-coding-agent。开发前固定一个经验证的版本组合；历史 @mariozechner 包名与新 API 不混写。此处记录调研状态，不要求为了新包名追 main。[S04][S05]

首版使用受控 ResourceLoader，显式指定工具、模型和应用专属工作目录；关闭用户工作目录、媒体目录及全局目录中的隐式脚本/扩展发现。不使用“默认 createAgentSession() 就安全”的假设。官方 Full Control 示例证明可显式接管这些边界，但本项目的工具白名单和资源规则需自行实现。[S06]

10.2 Pi 的职责与禁止项

Pi 负责	业务服务/工作流负责
接受目标、规划步骤，并在授权内提交/更新策略	Schema 校验、预算、授权与策略版本发布
调查综艺歧义，据证据调用身份/内容映射工具	校验本地对象、人工锁与集覆盖关系后正式提交
补全元数据并执行范围内修正	字段锁、来源优先级、身份修订与记录
调用搜索/下载/整理工具，调查异常并执行获准恢复	重试、文件操作、持久任务、核验与补偿
基于脱敏页面提出提取方案	Adapter 测试、审核、版本部署

默认不提供任意 bash、任意 SQL、任意文件写入、任意网络代理、无范围永久删除、读取 Cookie/Token、安装依赖或修改生产代码工具。必须提供受范围约束的正式执行工具，包括下载提交、Copy/Move、映射修正、规则更新和符合策略的缓存清理；不能用禁用通用工具替代这些必要能力。需要额外授权的操作必须由服务器验证有效的授权记录；模型声称“用户已同意”无效。已启用的自动策略本身可构成范围内的持续授权，正常步骤无需反复弹确认。

Pi 官方明确不自带完整的文件系统、进程、网络与凭证权限系统。禁用危险工具只是第一层；进程权限、容器挂载、网络白名单和业务授权都要独立落实。第三方可执行扩展首期不开放。[S04]

10.3 能力注册中心

统一 Capability 定义 ID、版本、输入/输出 Schema、权限范围、风险级别、幂等要求、是否支持预览和执行处理器。Web、内部 Pi tools、CLI 与 MCP 使用相同业务能力，不互相绕过权限。

不把整个管理 API 或任意 HTTP 请求工具自动暴露给模型。按任务发现具有明确范围的读写能力，至少覆盖：catalog.lookup、release.search/inspect、policy.preview/apply、identity.resolve、metadata.apply、download.plan/submit、organize.plan/execute、task.inspect/cancel/retry、cache.cleanup，以及 browser 和授权检查能力。上述为本项目能力名示意，正式命名待接口设计；每个 execute/apply 均验证本次或持续授权。仅提供 propose/preview 工具不能通过 Agent 自动化验收。

// 产品自有接口示意，不是 Pi SDK 原生 API。
interface CapabilityContext {
  actorId: string;
  taskId: string;
  scopeIds: string[];
  signal: AbortSignal;
}

interface MutationPlan {
  id: string;
  operation: string;
  targetIds: string[];
  expectedRevision: number;
  evidenceIds: string[];
  payloadHash: string;
  requiresApproval: boolean;
}

计划由业务端生成与保存。单次审批绑定 plan ID、payload hash、对象 revision、范围和有效期；持续授权绑定策略版本、动作与对象范围及预算。执行前重新校验。更换候选或路径后，旧的单次批准失效；若仍在有效持续授权范围内，可生成新计划并自动校验执行。幂等键由服务器基于操作语义生成，不能信任模型自行挑选。

10.4 Skills、规则与 Plugin 的区别

Skill 教 Agent 如何完成一个任务；Policy 是发布后可确定执行的用户规则；Plugin/Adapter 增加代码能力。三者分别版本化，权限不能通过 Skill 文本扩大。

借鉴 MovieClaw 的 Markdown Skills 交互思路，但不照搬任意同名覆盖立即生效。首期 Skill 进入注册和校验流程，发布遵循其变更权限；使用内容 hash 固定运行版本，记录所需能力、预算、所用模型配置和测试样本。Agent 经明确授权可在指定范围提出并发布通过历史样本回放的规则修订，保留回滚；这不等同于允许修改生产代码。未审查脚本不能因写在 Skill 中就运行。[S03]

推荐首批 Skill：综艺正片判断、元数据冲突分析、身份映射建议、下载失败诊断、站点提取修复建议。一个 Pi 会话处理一个有界任务，是否允许派发子代理由用户配置；开启后仍限制并发、总预算和工具范围，不默认建立无限多 Agent 群聊系统。

10.5 成本与模型失效

首期不设置轻量/强模型分档与自动路由。优先规则、历史确认和必要详情补充，需推理时使用用户配置的 Pi 上游与模型；解决不了再进入待处理中心。前端提供上游接入、模型选择、支持的思考档位、上下文预算、压缩策略及子代理开关。能力以固定 Pi 版本和上游实际支持为准，不假定所有模型都有同样档位，也不假定派发子代理属于 SDK 自动提供的功能。

压缩保留目标、约束、证据引用、已完成动作和剩余事项；正式业务状态存数据库，不依赖压缩摘要。子代理继承父任务授权上限，共享总预算与取消状态，写操作走同一能力服务和幂等账本；不能靠派生会话扩大权限或绕过硬阈值。

每个任务设置调用次数、token、时长和费用预算。推理缓存键包含规范化证据、节目上下文、规则/模型/Skill 版本，不能只按标题缓存。任一重要证据变化使旧结果过期。

禁止把 Cookie、passkey、私有下载 URL、无关全库内容送给外部模型。网页和 RSS 内容视为不可信数据，不能覆盖系统指令。模型超时或超预算时进入 attention，已确认的确定性自动化不停止。

10.6 自然语言执行交互

默认在授权范围内边执行边汇报，展示理解的目标、计划、进度与理由，用户可纠正或停止。“先给方案”只调查/规划，不提交下载或文件变更。已有授权覆盖的明确部分直接推进，歧义部分单独处理，不能一个疑问卡住整个批次。

例如“补齐某导演的电影”可先按明确说明的导演长片范围处理，监制作品另行确认；未找到合格资源的作品保存为待补目标。取消停止未来步骤，不自动删除已下载或已入库文件。执行涉及未被授权的删除、换源或长期规则扩大时，单独处理所需授权。

10.7 后台自主运行与目标闭环

Agent 的工作必须由持久任务触发和承接，不能仅由聊天 HTTP 请求驱动。典型触发源包括用户委托、定时主动选片、站点新增资源、需要判断的下载完成事件、识别歧义与异常恢复。确定性处理已能完成的事件不必调用 Agent；需要判断的事件生成有界任务，带目标、范围、证据引用、预算与恢复位置。

同一目标/根因的事件合并并去重，对反复失败设置退避与有限尝试。无新证据时不能反复花费模型预算；新证据或用户纠正到来时可以重新唤醒。Agent 运行中派生的事件需防止递归自触发风暴。上述是应用与执行器的职责，不宣称 Pi 自带整套业务调度。

关闭页面或聊天断线不取消已提交目标。等待下载、做种或人工处理时释放模型会话执行资源，业务目标和恢复条件保存在数据库；事件到达后继续相关流程。中断恢复时读取已完成工具动作，不能把压缩摘要当唯一状态。

统一待处理中心展示自动调查进度和结果；仅缺少授权、证据冲突无法消解或尝试/预算耗尽的事项需要人工决策。问题被 Agent 解决后自动核验、关闭对应异常并继续依赖任务。需要手动换源、突破硬阈值或未授权删除时仍按已确认边界处理，不能借“自动化优先”扩大权限。

完成标准以可核查结果为准：目标内容和启用 Slot 得到满足，文件已验证、正式映射与整理记录提交；有缺口则保持等待并标明原因。工具返回“任务已提交”只能显示已提交，不能立即汇报已入库。

11 工作流、幂等与崩溃恢复

11.1 持久任务管过程，Pi 管有界推理

推荐任务包括 ingestFeed、resolveObservation、evaluateAcquisition、submitDownload、verifyAndImport、refreshMetadata、reconcileLibrary、cleanupDownloadCache 和 resolveDecision。每类任务有输入与处理器版本，保留租约、尝试次数、重试时间与恢复入口。升级不能直接用不兼容处理器消费旧任务。

本版优先验证 OpenWorkflow，尚未锁定生产依赖。无论采用哪种执行器，外部操作都记录计划、执行尝试、结果证据和恢复策略；失去租约的 worker 不得再提交业务状态。必须覆盖“外部动作成功但结果未落库”的恢复窗口。

OpenWorkflow 集成验证门槛

用“提交下载 → 等待完成 → Copy/Move → 核验登记 → 等待保留条件 → 缓存清理”验证一条完整纵切。检查 Deno 下安装与运行、PostgreSQL 驱动、定时等待、重启恢复、取消、重试、授权提前到达和旧流程跨代码版本运行。

故障注入至少覆盖：qB 接收请求后断连、复制完成但步骤结果未提交、数据库断连、重复投递、工作进程丢失租约，以及流程运行中升级代码。业务核验与操作记录解决外部副作用窗口，不能只检查引擎任务最终为 succeeded。通过后可直接作为第一版组成部分；失败则记录可复现缺口再比较替代方案。只保留清晰的执行接口，不提前实现第二套引擎。

11.2 一次逻辑操作可以重试，但不能重复产生有效副作用

业务事件先随事务写入 outbox；调度器创建持久任务。若执行器支持与业务变更同事务入队，应验证并采用；否则保留幂等键与补投递。处理成功后标记投递状态，重复投递由领域服务去重。

下载请求先保存计划与预算预留。若 qBittorrent 接收成功但接口响应丢失，恢复时按任务关联与 torrent 标识查询实际状态，不盲目再次创建。双版本并发按本地内容单元和 Slot 原子预留。

文件已复制但数据库未提交时，恢复器读取操作日志，检查目标文件与计划证据后收尾；不覆盖现有文件，不轻易重做大文件复制。不宣称跨 PostgreSQL、下载器和文件系统的端到端 exactly-once。

11.3 授权记录必须持久化

Approval 或策略授权必须先写业务数据库，再唤醒任务。任务进入等待前、唤醒后及超时复核时查询有效授权，不能依赖聊天文本或一次即时信号。撤销、过期或 revision 不匹配使授权失效；用户只批准本次操作时不能提升为长期规则授权。

如果采用 OpenWorkflow，需要在锁定版本下验证 signal 是否持久保存与提前到达语义；不依赖此前 main 文档描述作为生产保证。[S08]

11.4 Agent 重试与任务取消

保存 agent_run、输入证据版本、输出提案和已提交工具动作。重启可从原会话恢复或重新启动推理，但所有写入仍经过同一操作账本去重；重新生成答案不能重放已经完成的下载或改映射。

取消是停止未来步骤并传播 AbortSignal，不代表撤销已经完成的外部动作。下载器任务是否暂停、临时文件如何处理，必须由显式补偿策略决定。长时间下载以下载器状态对账，不让 Pi 会话一直等待。

12 数据模型与接口边界

12.1 逻辑实体清单

以下是逻辑模型，不要求每个概念第一天都建成独立大表；但身份、资产、版本目标和执行状态必须分离。

域	建议实体	关键约束
内容	media_entity、content_unit、unit_relation	本地 UUID；编号可变，内容关系可修订
身份	external_identity、identity_revision	提供方+对象类型+外部 ID；候选与已确认分开
元数据	source_snapshot、metadata_field、field_override	原始证据保留；人工字段锁不能被刷新覆盖
文件	media_asset、asset_location、path_binding、library_root	资产与位置分离；已绑定路径不重算
来源	site_account、feed_source、observation、source_release	站点限流共享；多 Feed 观察关联同一资源
浏览器	browser_provider、browser_session、browser_tab、browser_control_lease	站点/账号隔离；会话控制权互斥；接管及恢复状态持久记录
规则	subscription、policy_revision、acquisition_slot、preference_tag、preference_suppression	独立 Slot；偏好范围/来源；取消不被自动重加
执行	acquisition_plan、download_task、asset_operation	幂等、前置条件、预算预留、恢复日志
人工/AI	decision、approval、automation_grant、agent_run、artifact	提案不直接晋升事实；审批绑定计划内容
运维	audit_event、outbox_event、reconcile_run、server_mapping、api_key	对账可恢复；外部库存时间/证据；密钥可限权与撤销
检索	title_alias、identity_candidate、identity_redirect、resolution_attempt	候选与正式实体分离；合并保留引用；重试有界
整理	organization_record、organization_file_result	操作前后路径、逐文件结果、增量游标；与资产操作关联

使用关系字段承载稳定查询和外键，JSONB 保存来源原文、规则参数和演进字段。避免把全部数据塞入一个 JSON 文档，也不把每个解析字段拆成复杂 EAV 通用平台。

12.2 事务与索引约束

已确认身份建立来源命名空间唯一约束；同一库根与有效相对路径不得被不相关资产同时占用；一个 Slot 的当前有效执行预留不得被并发创建两次。多位置指向相同资产允许存在，不要求文件内容重复存储。

观察与日志按时间保留或分区；关键查询至少索引来源资源 ID、本地实体、Slot 状态、待重试时间和路径绑定。大列表使用游标分页，避免全库传入浏览器或 Agent。

12.3 对外接口

REST/OpenAPI 与 MCP 均为正式产品入口，内置 Pi Agent 通过程序公开的 API/MCP 能力合同完成主要管理操作；MCP 不再只列为外部 Agent 的可选功能。界面、CLI、内置与外部 Agent 共用同一能力服务、授权、审计与幂等。传输可采用 MCP client 或同合同的进程内桥接，该实现选择待验证，不能改变用户可见能力或绕过业务权限。新增 API 不自动获得 Agent 暴露权限，需声明工具范围和参数合同。

接口应区分 read、preview、propose、approve 和 execute。敏感操作输出 task ID 或 plan ID，由任务页追踪；不要求长 HTTP 请求一直保持到下载完成。SSE 用于状态与 Agent 文本增量，断线后可按序号补读业务事件。

12.4 整理记录入口与开放合同

前端提供整理记录列表/详情和手动发起整理入口；自动和手动产生同格式记录。API Key 鉴权后可查询，读整理记录与发起整理使用不同权限。外部程序根据记录适配媒体服务器，首期不要求内置 webhook 或直接刷新。

字段组	最低合同
身份	稳定 record ID、task/operation ID、作品/内容关联、触发者与手动/自动来源
路径	整理前路径、整理后路径、下载器/库根及路径视图标识，避免跨实例同路径歧义
动作	Copy/Move/重命名/目录调整、开始与完成时间
结果	queued/running/succeeded/partial/failed/cancelled、失败原因与跳过原因
文件明细	目录或种子任务可展开每个文件的前后路径和状态，不能仅返回目录级成功
增量读取	按稳定变更游标分页，包含既有记录状态更新；客户端可去重并断点续读

以上为本项目建议字段名和合同草案，不是声称 MP 原接口同名；正式 OpenAPI 在实施时冻结。前后路径仅在已知且获授权范围内提供，不输出凭据。源文件存在但整理失败时不伪造目标成功记录。

12.5 多实例路径映射

qB 与程序是否同机不构成限制，按实例配置下载器路径到执行进程可访问路径，再关联媒体库根与外部服务器路径视图。Docker 容器内路径即使字符串相同，也需验证指向正确挂载。程序必须确实可访问源与目标文件，纯字符串映射不提供跨机器文件访问能力；可通过共享挂载解决。

配置时验证可读写、挂载健康和路径重叠；跨卷 Move 使用可恢复 Copy→核验→删除源流程。路径映射更新不等于整库物理迁移，不纳入底层磁盘调度。

13 界面、安全与可观测性

13.1 控制台信息架构

首页显示完成事项、目标缺口、来源异常和待决定事项。主要工作区包括媒体库、订阅与收录规则、可编辑偏好标签、PT 站点工作台（整理/原站视图）、来源/Feed/快照、下载与任务、整理记录、待处理中心、身份与元数据、系统设置（实例、路径、API Key、Pi 上游和预算）。

媒体详情页应同时展示：实际路径、外部身份映射及状态、元数据来源、各 Slot、候选拒绝理由、下载历史与校验结果。Agent 是与完整控制台并列的正式入口，可使用上下文侧栏和独立会话页，读取当前对象无需复制 ID。主要媒体管理操作两边可达，操作结果、配置、任务进度即时共享。凭证输入、授权范围变更及需要本人完成的浏览器验证使用专门 UI，Agent 可引导进入。

待处理中心按作品和问题类型合并，展示证据、建议、影响范围与预览，支持确认一次相同根因。登录挑战、身份冲突、正片歧义和路径冲突都进入同一入口，但使用不同权限与操作模板。Agent 先在授权范围内调查、有限重试与恢复，解决不了才请求人工；同根因合并，单项异常不阻塞无关任务。Telegram 等消息渠道未列为已确认必需项。

13.2 安全控制

首期只有一个人类管理员和全局策略，不建设多用户体系；API Key 与自动化执行身份可分别只读或限制操作范围，并可单独撤销。凭证加密存储，主密钥与数据库备份分离保管；日志、快照、错误与导出执行统一脱敏。私有 URL 的 query token 不作为模型输入。

来源 URL 和回调实行服务类型与目的地址限制。需要访问内网 qB/Emby 的白名单独立于外部 PT 页面，不能让任意 RSS 跳转或 Agent 工具触达未批准内网地址。

默认只运行随产品审查发布的 Adapter 与扩展。确需第三方可执行代码时单独设计沙箱和凭证代理，不因为其使用 TypeScript 或叫“插件”就视作安全。

若后续采用 OpenWorkflow，其 Dashboard 官方文档提示不内置认证。不能把它原样公开；首版控制台自行承载业务任务视图，原始工作流诊断界面仅内网管理员可达，后续受控集成再验证授权边界。[S07]

13.3 可观测指标

记录 Feed 抓取成功率和延迟、候选重复率、识别待确认率、错误收录率、Slot 缺口、下载/入库失败、路径变更、挂载异常、Agent 调用成本和审批超时。trace ID 贯穿 observation、plan、download、asset、workflow 和 agent_run。

识别准确率基于人工标注样本；RSS 漏项率只有具备可比较基准时才计算。不得用模型自评替代准确率，也不把站点不可访问时的零条目记录为“正常没有更新”。

13.4 MP / MovieClaw 可观测性与展示复审

本次基于已固定的 MP V3 与 MovieClaw main 源码快照，核对后端字段/接口、MovieClaw 前端组件及相关设计文档；没有启动参考项目或检查运行截图，因此本节是业务与实现对照，不是已完成的视觉/性能评测。以下“已见”仅指对应提交的代码或文档，不泛化成所有版本的产品保证。[S21][S22][S23]

13.4.1 对照与采用决定

参考能力	源码证据	本项目采用方式
MP 整理记录可追溯	TransferHistory 包含 src/dest、mode、分类规则及策略版本、失败阶段、恢复动作、清理状态和文件列表	整理记录展示前后路径、选择依据、逐文件结果、失败步骤和可执行恢复，不只给成功/失败图标
MP 首页统计与运行进度	DashboardQueryService 聚合媒体数与整理趋势；dashboard 端点提供下载器/存储等信息；scheduler progress 记录进度、时刻与错误	首页优先业务产出、待处理和缓存水位；资源使用及技术指标下沉到系统健康
MP Agent 计划与实际运行	agent.md 定义目标/步骤/依据/阻塞；AgentTaskRun 有真实 run ID、触发来源、执行快照与结果	每次自动/手动 Agent 运行可追溯到目标、步骤和正式结果；不把任务提交当入库完成
MP 订阅批次语义	subscription/observability.py 区分完成、跳过、失败、取消及重新排队	搜索部分失败不能展示“全部搜索完成”；未搜、没找到、无合格资源分开
MP 技术指标接口	OTel 可选 adapter、HTTP route/status/latency、scheduler 时长指标	结构化事件和内部指标先落地；外接监控作为可选能力，不因内部使用强制部署一整套监控集群
MovieClaw 统一业务时间线	task-activity.ts 将 download 与 ingest Job 关联、共用分组/计数；task-center-view.ts 展示阶段	下载和入库串成一个业务过程，子任务展开；侧栏/首页/任务页同一计数口径
MovieClaw 根因告警与诊断上下文	download_health.py 按下载器/目录聚合，diagnosis_handoff.py 组装任务、路径、活动证据	一个挂载故障显示一个根因及受影响任务；Agent 自动先调查，人工无需复制日志
MovieClaw 忽略/撤销	job-attention.ts 将 dismissed_at 与执行状态分开；任务页有批量忽略/撤销	失败仍是失败，忽略只影响提醒；可持久静音重复自动调查，恢复显式可见
MovieClaw Agent 过程展示	agent-conversation-view.ts 有折叠工具调用、结果、上下文压缩卡和耗时/用量信息	对话默认展示结论与当前步骤，展开看工具证据、耗时、压缩和预算，不堆叠原始日志
MovieClaw 真实数据卡片	agent-media-cards.tsx 按模型返回 ID 请求正式接口，复用媒体卡片；agent-activity.ts 避免流式输出不断重排会话	作品/资源/任务卡片引用本地 ID，状态来自业务 API；固定占位和稳定排序，防止页面抖动

13.4.2 必须调整的参考行为

• MovieClaw 的手动“交给 AI 分析”入口可保留，但我们的默认是 Agent 在授权内先调查，只有无法解决时才要求人处理。
• 不采用自动换源；下载停滞只生成诊断，换源仍需用户委托。忽略通知也不解除磁盘硬阈值、HR 或授权限制。
• MovieClaw 以 infohash 串联下载/入库的思路可参考，但本项目支持多下载器，关联键必须包含实例身份，不能把两台 qB 的相同 hash 混成一条。
• 不把 MovieClaw 的观看页/播放统计或默认观看落点作为我们的首页；首期重点是自动整理入库，不扩大为媒体播放运营台。
• 普通下载和入库历史应简洁，但本项目 Copy 源文件仍有保留/清理生命周期，不能把所有完成做种任务从界面完全隐藏；单独提供下载缓存/保留视图。
• 目录为空只是观察，不能仅凭这一点断言挂载失效；沿用挂载哨兵与多项核验，未确认时明确标“疑似”。
• 参考卡片的真实数据来源，但区分 404、不具权限和网络失败；不要全部显示“未找到”，更不能据此重新下载。

13.4.3 首页与详情的展示合同

首页先回答四件事：系统是否在推进目标、已经完成什么、还有什么缺口、是否有事项真的需要人。建议固定以下区块，均来自正式状态投影：

区块	必须回答的问题
自动化概览	今日新增作品/内容单元、升级、已核验入库文件数；自动完成与 Agent 参与完成；去重口径清楚
当前工作	正在搜索/下载/整理/核验/Agent 调查的业务目标，以及正常等待的原因
需要我处理	根因级事项、影响作品/任务数、Agent 已做的检查、剩余决策与可执行操作
缓存与保留	实际使用率、在途空间预留、硬阈值/恢复水位、可清理量及 HR/保留锁定量，统计未知时说明
来源健康	四站、qB、Emby、浏览器、模型上游的最后成功时间、延迟、失败原因与快照新鲜度
最近产出	新增了哪几集/哪种版本，整理前后路径、部分成功/跳过原因，点击进入明细

作品详情以“内容单元 × 已启用版本目标”展示完整性：例如第八期上/下分别对应 1080p 与 4K；空缺、下载中、已核验、等待版本升级各有明确文本，不只依赖颜色。未经配置不自动为全部综艺创建双版本。

候选详情回答“为什么选/不选”：保留资源证据、规则版本、命中/排除项、缺失字段、与现有版本差异及 Agent 简短判断依据。该说明是可审计的依据摘要，不要求存储或展示模型私有思维链。高级页面可展开原始标题和脱敏响应，不让技术细节占据日常首屏。

任务详情沿业务阶段展示时间线及子任务；每阶段区分排队、执行、等待、重试、部分成功和失败。可量化时显示已处理文件/总文件或字节进度；总量未知则显示阶段与已完成数量，不能伪造总百分比。成功说明限定本次处理范围，例如“本次新增 S02E03–E05”，不能写成“整部剧已齐”。

13.4.4 Agent 运行台与动作展示

每次运行至少显示：目标、触发来源、作用范围、当前步骤、已完成动作、等待原因、最后进展时间、下一次唤醒条件、结果证据与暂停/取消入口。子代理开启时展示父子任务关系、各自状态和共享预算；未启用时不显示空的多 Agent 看板。

工具卡片显示能力名、脱敏参数摘要、开始/结束时间、状态、结果/错误和业务对象链接。对话正文、任务页、整理记录及待处理中心共享同一运行/操作身份；引用不存在或暂不可读的对象时给明确占位，不由模型补造卡片内容。

用量面板按需展开上游/模型、实际输入/输出/缓存 token、延迟、重试次数和压缩记录。上游未报告的数据为未知；估算费用标注估算及价格口径，不伪装成账单。上下文压缩显示发生时刻和保留目标摘要，不丢失业务进度。流式 token 不改变会话排序，不让长工具结果撑坏布局。

13.4.5 告警、事件与技术观测

“正在自动处理”和“需要人工决策”分别计数。告警带根因键、首次/最近发生、重复次数、影响范围、证据、Agent 尝试、下一步动作与恢复条件。静音、忽略、解决、取消是不同动作：忽略不变更执行结果，不释放仍占用的资源锁，不解除硬保护；有明确新证据或影响扩大时按策略重新提醒，不能永久掩盖新故障。

业务事件、调试日志和指标分层：业务事件保存目标/任务/运行/操作 ID、事件序号、发生时间、来源、状态变化、证据引用和规则修订；日志保存脱敏诊断；指标统计吞吐、延迟、失败率、积压、缓存命中与模型消耗。完整文件路径、hash、标题和 task ID 放日志/事件字段，不作为无界指标标签。日志/截图按配置保留，关键映射和操作证据不随短期日志一起清除。

实时界面经 SSE/轮询读取投影，断线后按游标补读并核对快照；后台处理不依赖页面在线。过期快照明确显示时间；一个下载器或站点故障不能让全页白屏。API 同样提供结构化状态/诊断能力供 Agent 查询，不能只有人可见的看板而 Agent 看不到根因。

工程接入优先级：M1 必须有业务时间线、整理记录、统一状态/计数、错误证据、Agent 过程和基本来源健康；M2 完善根因聚合、版本覆盖矩阵、候选理由及用量/保留视图。可选 OTel/外部图表放后，不作为内部第一版可用的前置服务。

14 如何借鉴 MoviePilot 与 MovieClaw

14.1 以具体实现为参考，迁移业务逻辑到 TypeScript

已确认的研发方式： 本项目用于用户内部媒体基础设施，采用 TypeScript/Deno 技术栈，以 MoviePilot 和 MovieClaw 的具体源代码实现为主要参考，进行业务逻辑迁移与适配。不限定为只学习产品外观或抽象架构，也不要求对成熟业务逻辑全部重新发明。

优先沿源代码调用链理解数据结构、条件分支、状态转换、事务边界、异常处理、重试/恢复、接口字段及相关测试，再映射到本项目的 TS 模块。Python/Go 到 TS 需要重新实现运行时、类型、并发和依赖接口；MovieClaw 已有 TS/React 前端，也可作为直接的实现级参考。语言不同不意味着只能做外观模仿，也不意味着机械翻译便能保持行为正确。

本项目采用自己的业务核心和部署结构，不 Fork 整个上游服务作为主系统；这与迁移上游具体业务算法并不冲突。符合我们目标的成熟分支优先保留，只有与本地 UUID、多 Slot、Agent 优先或已确认授权规则冲突时才调整，并写明原因。

MoviePilot V3 官方文档已描述多来源媒体身份、版本化分类规则、路径快照、Agent、可靠后台事件与恢复机制。不能把它概括为“只认 TMDB、没有 Agent、没有持久化任务”。本项目的差异是把本地身份、稳定路径、综艺内容覆盖和多 Slot 一开始就作为核心验收标准。[S01][S02]

MovieClaw 官方 README 展示了既有目录接入、待识别队列、并行版本、CLI 驱动助手以及 Markdown Skills 等设计。源码已确认有 local 来源、本地库存与可配置 MCP；但 AgentRunner 自实现，Skills 借鉴 Pi，不能等同于使用 Pi SDK。物理多版本共存不等于多个 Slot 独立维护，具体边缘情况仍需实例测试。[S03][S16]

参考项目	值得研究的部分	新项目如何吸收
MoviePilot	下载/整理链路、站点 Adapter、失败恢复、来源合同	对照具体调用链与测试，迁移识别、文件选择、冲突分支与恢复逻辑，适配本地领域模型
MoviePilot	策略修订、路径快照、多来源身份	参考数据结构、校验条件和提交顺序，迁移到 TS/PG，保留稳定路径要求
MovieClaw	既有目录、待确认队列、任务与告警展示	参考实际扫描/任务聚合/根因分组函数及前端组件，迁移适配到统一业务合同
MovieClaw	CLI、Skill 与 Agent 能力组织	参考工具组织、诊断上下文和数据卡片实现，推理循环使用 Pi，写操作经过统一 Capability
Pi	成熟会话与推理循环	SDK 嵌入并封装，限制资源发现和工具
OpenWorkflow（优先验证候选）	PostgreSQL 持久步骤与 worker	经恢复和版本升级验证后再决定；业务幂等、授权账本独立

14.1.1 MP 专项业务对照（待核验，不是已实现结论）

用户明确要求多文件种子、整季包和目标已存在时参考 MoviePilot 的业务方案及逻辑。对照固定提交，沿实际调用链阅读入口、识别、文件选择、整理、冲突处理、结果登记与恢复，而不是只读类名或 README。

专项	必须查清的问题	交付证据
多文件识别	如何识别作品/季集/附加内容；混合内容、跳过文件、部分失败如何记账	源码路径/函数、输入文件清单、逐文件预期行为
整季包	已有/缺失/升级如何决定；下载选择与整理范围如何区分；多集单文件怎样表达	单集/整季混用、部分已有、质量不同的对照样本
目标冲突	同名同内容、同名不同版本、旧任务残留如何判断跳过/覆盖/升级	分支条件、前置核验、覆盖权限及恢复结果
中断恢复	搬运完成但登记失败、跨卷移动、部分成功怎样恢复	操作记录/检查点/核验调用链和故障注入样本
源数据清理	什么状态才可清源；未处理文件、共享路径及 qB 引用如何保护	清理条件与文件级引用检查

采用 MP 的成熟逻辑时，须适配本地 UUID、独立 1080p/4K Slot、综艺分段覆盖与本项目授权。不能因 MP 某个默认允许覆盖，就视为用户已授权本系统覆盖所有文件。代码复用许可另按下一节核验。尚未完成本专项的逐函数/运行对照，不将它列为已完成研发。

14.1.2 两项目实现迁移的交付规范

每个需要借鉴的模块建立简明对照记录，至少包含：上游仓库及精确提交、文件/函数、输入与输出、关键分支/状态、对应 TS 模块、保留的行为、调整项与原因、验证样本。源码是主要依据，README/设计文档提供背景；二者不一致时检查实际执行入口，必要时在参考环境复现。

模块	主参考	迁移重点
元数据识别与刮削	MP（优先）	识别入口、多来源取数、字段归并、季集映射、NFO/图片写入、缓存/重试及人工修正
视频文件转移入库	MP（优先）	入库计划、路径与命名、文件/附属文件处理、Copy/Move、目标冲突、核验、历史登记和中断恢复
下载、多文件/整季包	MP	文件选择、已有/缺失/升级判断、混合集处理及与转移模块的交接
站点访问、搜索、分类和增量同步	MP + MovieClaw	实际请求/响应、解析规则、缓存与游标；共用适配层而非强行统一站点差异
旧库登记、待识别项和库存关系	MovieClaw + MP	扫描增量、文件关联、候选处理；适配本地稳定 UUID
Agent 工具、诊断及操作反馈	两项目 + Pi	工具合同、证据打包、运行记录与结果核验；Pi 承担推理循环
可观测性和前端展示	MovieClaw + MP	业务时间线、统一计数、根因告警、整理记录、真实状态卡片
持久执行与一致性	MP + MovieClaw，OpenWorkflow 候选	迁移业务操作与恢复要求；通用调度优先交给验证后的引擎，不机械搬两套执行器

验证优先使用具有业务区分度的输入样本和故障窗口：正常输入结果对齐；刻意改变的行为有说明；未知情况保持明确状态。默认不自动换源、双版本互不淘汰、人工映射锁定等本项目决定优先于上游默认。

上述对照表是研发要求，不表示所有模块已经完成移植或逐函数核验。现有源码初步调研和可观测性复审可复用，后续深入到每个实际实施模块。

14.1.3 MP 元数据刮削与视频转移入库（优先专项）

用户明确指定这两个模块作为实现级参考重点，与 Agent 工具、可观测性同样进入核心研发范围。以下是必须追踪的业务问题，不表示 MP 每条行为均已核验或可以原样移植。

元数据识别与刮削： 沿标题/文件名识别、候选检索、外部身份确认、详情获取、字段归并、季集映射、NFO 及图片写入的实际调用链研究；核对语言优先级、缓存、失败重试、人工更正、已有文件覆盖条件，以及下载前信息与下载后探测如何配合。参考 MP 的具体解析与处理逻辑迁移到 TS，外部服务通过适配器接入。身份映射、元数据补全和磁盘投影分别记录状态。

适配本项目时，本地 UUID 保持主身份；TMDB 缺失不阻断证据充分的本地入库；人工锁定字段不被刷新覆盖；刮削改标题不改变已有路径绑定。Agent 可在授权内补查、消解歧义并调用同一刮削能力。NFO/海报写入受目录策略控制；图片或外部元数据暂时失败应独立重试，不重做已成功的视频搬运，不伪报全部步骤完成。

视频文件转移入库： 对照 MP 的下载完成/手动整理入口、文件枚举、媒体及季集识别、目标目录与命名规则、附属文件关联、冲突/重复处理、实际转移、结果核验、历史记录及下载器收尾。重点查明多文件部分成功、跨卷 Move、目标已存在、进程中断和源文件清理的实际分支、提交顺序及恢复依据。

我们优先采用经过验证的 MP 业务处理方式，再适配独立 Slot、综艺分段覆盖、qB 标签、路径映射与 HR 保留条件。Copy/Move 为主要模式；完成态依据文件核验和业务登记，不仅依据文件调用返回。字幕、NFO、图片等附属文件的配对和命名处理要纳入对照；无法确认归属时不误搬或误删。硬链接仅按既定兼容范围处理。

交付与验收： 两条链路都给出源函数到 TS 模块的映射、关键输入/输出、条件分支、状态转换和恢复样例。使用同一组脱敏文件名、媒体返回数据与目录场景比较行为；覆盖错误识别修正、TMDB 缺集、元数据刷新不改路径、附属文件归属、部分失败和跨卷 Move 中断。保留本项目已确定行为与上游的差异说明，避免将“参考 MP”变成未定义的全部兼容承诺。

14.2 代码复用与许可证

本次源码快照中 MoviePilot 后端 LICENSE 为 GPLv3，README 有学习交流及传播方面声明；不能将 GPLv3 简化为禁止商业使用。分发、代码合并或商业化时，核验拟用提交、文件与站点资源许可及适用义务。[S01][S10]

本次访问的 MovieClaw main 分支 LICENSE 写明：v0.27.0 及以前仍适用 MIT，之后为附加条件的修改版 Apache 2.0，商业使用需书面授权，衍生版本有继续适用条款。后续源码核对发现 main 的 pyproject 版本字段仍为 0.27.0，而 LICENSE 已带附加条件；不能仅凭版本字段或旧 raw 缓存认定 main 为 MIT。必须核对拟用历史 tag 及文件随附许可。[S11]

Pi 当前仓库列 MIT，OpenWorkflow 仓库列 Apache-2.0；仍需在锁定版本后检查随附依赖与文件许可。[S04][S14]

默认实施方式：以两项目具体实现为参考进行 TS 迁移与适配，保留必要的来源、许可与修改记录，不设置“只能参考思想、不得参考实现”的额外限制。拟采用的适配器、提示词、数据和依赖按实际来源核验；构建使用固定版本，不自动追随上游 main。内部使用是本项目用途，不作为忽略所用材料条款的理由；跨语言翻译或 AI 改写也不自动使移植成为无来源的独立原创。

确需复用时建立 component ledger：来源、精确提交/版本、文件路径、许可证、修改记录、NOTICE 与分发方式。历史 MIT 代码仅限已核验的历史版本，不把后续限制版本改动混入。上述为工程合规边界，不替代针对拟发行产品的法律审查。

15 实施阶段与验证顺序

15.1 M0：先证明底座能安全工作

固定 Deno/Pi/PostgreSQL/OpenWorkflow 验证版本，完成最小骨架与 Schema。准备脱敏的真实 RSS、综艺标题、既有路径和失败样本。所有自动执行关闭，先建立只读登记与影子决策。

必须通过：Deno 下 Pi/PG/MCP/OpenWorkflow 的实际兼容性；Pi 显式工具白名单和无隐式扩展；执行器崩溃恢复和流程版本升级；提前审批不丢失；多 Feed 并发不重复提交；现有媒体路径在改名与映射修订后保持不变。同步完成 MP 多文件/整季包/目标冲突的源码行为对照，形成后续纵切用例。浏览器先连接用户现有 camofox-browser，在已授权站点验证结构化提取和同会话人工/Agent 交接；固定版本、认证与凭据处理，记录 linuxserver/chrome/Selkies 是否适用以及不能直接互通的边界。

15.2 M1：单条完整链路

先做观众与馒头两类站点、多个 RSS、qB 标签接管、Copy/Move、一个电影目标和一部常规剧集：观察、匹配、计划、下载、验证、固定路径入库、整理记录 API 和可选 Emby 兼容库存查询。同步实现数据库备份、审计、恢复和停用自动化开关；站点工作台先做列表、详情、库存标注与统一下载入口。

M1 就必须验证 Agent 接受自然语言目标，自动查库存/搜索、选择资源、提交下载，并在下载完成后经任务系统继续识别、整理和核验，最终汇报真实结果。至少验证一次授权内异常调查与恢复。确定性规则和文件服务承接执行，Agent 不只解释失败或提出草案。未完成整个目标时保存缺口与等待条件；关闭聊天不影响后台推进。

15.3 M2：交付核心差异化需求

完成国产综艺内容分类和分段覆盖、本地临时集账本、独立双版本、PT 新作品/追更/升级三种规则、浏览器 Adapter、完整站点工作台双视图和同会话人工接管、映射巡检及辅助刮削、旧库分范围接管、授权规则优化与条件/Agent 选片、缓存硬阈值及清理、偏好标签、站点快照缓存、跨季召回与待识别治理、双入口待处理。完成憨憨与 CHD 适配、媒体级主动整理。

该阶段才构成覆盖本次全部核心痛点的产品首版候选；不能把只做完 RSS 下载的 M1 宣称为整个需求已经完成。先用影子模式比较人工选择，再分节目、分站点开启自动收录。

15.4 M3：扩大适配与运维能力

加入更多 PT、Transmission/Plex 等适配，完善历史样本回放、Skill 管理、CLI 和 MCP 扩展能力、规则迁移和页面提取修复提案。开放插件生态、小模型训练和高吞吐原生工具放在真实瓶颈出现之后。

不在当前给固定工期承诺。主要不确定性是实际站点差异、综艺样本覆盖和生产恢复测试，不能仅按代码生成速度推算交付。应以每阶段验收证据而非页面数量判断进度。

16 验收场景与指标

16.1 必须覆盖的端到端用例

编号	场景	通过标准
AT01	同站三个 RSS 同时出现同一条资源	一条资源、多来源记录、一个有效下载计划
AT02	两个 PT 发布同作品不同版本	不误合并；正确进入各自 Slot 候选
AT03	RSS 停更/窗口丢失	标记来源异常并有界补漏，不伪报完整
AT04	综艺上/下、加更、完整版混排	不把加更作为正片；分段覆盖可解释
AT05	不同节目都出现“会员版”	按节目/来源规则处理，不全局盲目排除
AT06	TMDB 未录入新一集	可建立本地单元并继续规则链；后续补映射
AT07	TMDB 改译名后又来一集	仍写入既有作品/季目录，不产生新译名目录
AT08	纠正 TMDB ID 或季/集对应	本地 ID、路径及历史不变，映射有修订记录
AT09	同媒体两个 Slot 同时缺失	分别预留与执行，不被单一完成状态提前停止
AT10	旧电影今天上传	不误当新上映电影；升级规则可独立命中
AT11	浏览器会话过期或需验证码	暂停并人工接管，不无限重试、不泄漏凭证
AT12	下载器收单后 worker 崩溃	重启后查到既有任务，不重复有效提交
AT13	文件复制后、DB 完成前崩溃	对账收尾，不覆盖、不重复大文件复制
AT14	NFS/FUSE 根暂时离线	不批量删除记录、不大规模触发补下载
AT15	用户在工作流等待前批准	批准存在数据库并最终被消费，不依赖信号时序
AT16	单次批准后计划候选或目标改变	旧单次批准失效；无有效持续授权时重新预览/批准，有持续授权时按新计划重新校验
AT17	模型断网或超预算	确定性链继续，歧义任务排队待处理
AT18	PT 标题带恶意提示词	只作为数据，不触发越权工具或凭证输出
AT19	做种源与媒体库为硬链接	不原地改媒体字节；清理遵循全部引用与做种检查
AT20	从备份恢复数据库	先只读对账；映射、Slot、人工纠错和执行记录可恢复
AT21	手工锁定译名或海报后自动刮削	锁定字段不被覆盖
AT22	Emby 兼容查询失败或外部刷新失败	标注未知/过期，不当资源缺失，不重新下载或再次入库
AT23	手动给已有 qB 任务加管理标签	纳管并识别；不改已有路径与其他标签；歧义待处理
AT24	移除管理标签或 qB 任务消失	停止后续自动操作，保留历史；不连带删除媒体库
AT25	Copy 完成后缓存可用空间低于阈值	只清理已验证入库且满足保留要求的源任务，不影响库副本
AT26	空间不足且全部缓存仍需保留	暂停新增下载，展示根因与可行动作，不提前删除
AT27	Move 跨盘时复制完成后重启	检查目标与操作记录后收尾，不提前删源、不误删最终库
AT28	Move 任务尚受 H&R 约束	等待或按已授权策略改 Copy；不能静默破坏做种义务
AT29	一个种子只完成部分文件入库	未处理文件保留，不能按整种“完成”清掉源数据
AT30	条件选片与 Agent 偏好选片	两种模式各自可配置，保存理由，均受预算及范围约束
AT31	人工纠错与 Agent 自主优化	人工纠错在相应范围生效且不被刷新覆盖；Agent 扩大长期规则需对应授权与回放
AT32	已启用正常自动策略反复触发	授权内自动执行，不逐次确认；冲突仅阻塞相关任务
AT33	旧库混合只登记/自动维护范围	仅启用范围自动补缺，作品覆盖正确；首次预览不提交下载
AT34	自动收录新剧第 3 集	按策略建立持续追踪并补缺；追新季可单独开关
AT35	页面失效与浏览器恢复	有界切换与调查；本人验证进入接管；凭证不进模型上下文
AT36	界面与 Agent 修改同一规则	共用 revision、校验和任务，冲突不静默覆盖
AT37	用户主动对选中媒体改目录	预览后执行并更新绑定；自动元数据刷新仍不改路径

追加访谈验收场景

编号	场景	通过标准
AT38	4K WEB-DL 与蓝光压制升级	合格蓝光压制优先；低劣版本不盲换；1080p 独立目标保留
AT39	条件选片与 Agent 同时选中同一资源	一个有效计划；硬排除不被绕过；偏好理由可查
AT40	手动删除 Agent 推断偏好	前端与对话状态一致，旧证据不使标签自动复活
AT41	达到缓存硬阈值再回落	阻止新下载，暂停授权范围任务，继续做种/整理；仅恢复系统暂停项
AT42	多 qB 共用缓存且有未纳管任务	统一核算实际及在途占用；不越权暂停；显示仍增长原因
AT43	委托 Agent 排查全实例	能调查未纳管任务；调查不导致删除/永久接管
AT44	用户追节目与 Agent 推荐节目	前者默认接续后续季，后者默认当前季；“仅本季”覆盖默认
AT45	TMDB 缺季、同名重启、简称变化	综合候选召回；可先建本地对象；不按模糊名称直接合并
AT46	候选反复识别失败与后续新证据	不创建大量正式空实体；有界重试、可查原因；新证据推动恢复
AT47	关闭站点与陈旧缓存	停止网络访问和新候选执行；历史可查；既有 qB 任务保留
AT48	整理部分成功、记录后续更新	文件级前后路径准确，增量客户端能读到状态变化并去重
AT49	Emby 有资源但无法确定来源版本	记录证据/时间/未知，不把猜测写成蓝光或把失败当没有
AT50	下载长时间无进展	创建待处理，不默认换源；用户明确委托才执行替代计划
AT51	Pi 上游不支持某档位或子代理关闭	UI 正确表达能力，执行不假装支持；关闭后不得派发
AT52	子代理重复请求和取消	授权/总预算共享，重复动作幂等，取消停止未来步骤
AT53	用户要求先给方案	只调查与规划；不下载、不搬运，不影响无关既有自动任务
AT54	整季包部分已有、部分缺失、目标冲突	按 MP 对照样本验证；不静默覆盖，不因部分成功清理整种
AT55	流程中途升级或丢失 worker 租约	按版本恢复或显式阻塞；旧 worker 不重复提交结果
AT56	数据库恢复、密钥撤销、实例路径改变	先对账再执行；已撤销 Key 无访问权；路径不可达不误删

PT 站点工作台验收场景

编号	场景	通过标准
AT57	四站列表/详情进入整理视图	字段统一但原始来源可追踪；缺字段不伪造，显示更新时间
AT58	工作台叠加本地与 Emby 库存	作品关联有证据；已收藏/缺版本/下载中与业务账本一致
AT59	缓存命中、失效与站点关闭	遵循缓存优先/按需补查；关闭不发起访问；失败不假装无内容
AT60	工作台下载与自动策略同时触发	共用去重、预算、硬阈值和 qB 标签，只产生一个有效提交
AT61	Agent 操作中人工接管	确认同一浏览器会话/标签页；控制权互斥，无后台争抢输入
AT62	人工登录或跳转后交回 Agent	重新获取页面/登录状态和元素引用，不重放旧点击
AT63	接管断线、浏览器重启或退出登录	暂停相关动作并显示状态，按实际会话能力恢复；不跨账号混用
AT64	原始页面含脚本、私有链接或凭据	整理视图用提取字段渲染；模型与日志无凭据；控制通道受认证
AT65	浏览器捕获种子文件后重复请求	受控暂存、核验并走统一计划；不写媒体库、不重复提交
AT66	独立 Chrome 与 Camoufox 同时存在	明确会话身份；不能将两个独立窗口冒充同会话接管

Agent 自动化优先验收

编号	场景	通过标准
AT67	一次委托完成常规媒体入库	在有效授权内，Agent 可调查、选片、提交并经持久流程完成核验/入库，无逐步骤人工点击
AT68	用户离线且下载后才出现歧义	后台唤醒有界 Agent 任务，查证后自动执行获准修正并继续；无法确定才需人工
AT69	页面关闭、进程重启与重复事件	目标持续、动作去重；从正式任务状态恢复，不能重复下载/搬运
AT70	工具只返回任务已提交	Agent 汇报提交状态并跟踪，文件核验成功后才汇报入库完成
AT71	同根因异常反复触发	合并调查、有限重试；恢复后自动关闭异常并继续，不循环消耗模型
AT72	已授权能力从 API/MCP 调用	内置 Agent 实际具有范围内执行能力；不能只暴露建议/预览造成流程永远等待人工

可观测性与展示验收

编号	场景	通过标准
AT73	一个下载产生多个入库子任务	业务过程只计一次，子任务可展开；多下载器相同 hash 不串联
AT74	多作品因同一挂载问题失败	根因聚合、影响清单保留；自动调查与需人工分别计数
AT75	忽略告警或静音重复调查	原失败和证据保留，支持撤销；不解除 HR、空间限制或资源锁
AT76	一个站点不可达且搜索部分完成	展示局部失败、快照时间与已完成范围，不伪报全成功
AT77	本次只入库三集且复制部分失败	展示准确季集及逐文件结果，不宣称整季齐全；进度不伪造
AT78	Agent 卡片引用无效或接口失败	正式接口取数，区分失效/不可读；无模型伪造库存
AT79	SSE 断线、旧快照或后台运行	可补读/校准，后台不停；计数一致，旧事件不覆盖新状态
AT80	工具日志/模型用量与决策理由	凭据不泄漏；未知用量不填零；依据可追溯，指标标签有界

16.2 建议质量门槛

安全性质优先设零容忍验收：在测试集中，无授权路径变化为零、重复有效副作用为零、未授权永久删除为零、密钥进入模型上下文为零。该目标需要故障注入验证，不可仅凭功能演示声称满足。

综艺自动分类采用精确率优先。可以将“获准自动通过的样本精确率不低于 99%”作为初始发布目标，但必须同时报告样本量、置信区间、自动覆盖率和未知节目表现；零误判小样本不等于线上 99%。达不到时缩小自动执行范围，不降低审批门槛。

性能测试需要明确文件数、目录深度、日观察量、并发下载数、挂载类型和硬件。重点测增量扫描、待处理延迟、数据库查询与恢复耗时；没有这些输入，不承诺 PB 级库的具体响应时间。

16.3 自动化效果的验收口径

除正确性外，记录正常任务无人干预完成率、每批任务人工介入次数、Agent 异常解决率、未解决事项年龄、每个成功入库任务的模型消耗，以及错误入库/误删/重复执行。分开报告确定性自动完成、Agent 参与后完成、需要人工和仍在等待的任务，不把缺资源/HR 等正常等待一概当失败，也不通过隐藏待处理项提高完成率。

在固定的常规验收样本中，授权一次后应无需逐步骤人工操作；歧义与失败样本分别验证 Agent 是否主动调查、核验和继续。实际生产百分比要通过影子与小范围运行建立基线，本文件不凭空承诺自动化成功率。

17 待落实事项与最终架构决策

17.1 产品行为已经确认

内部使用、Agent 自动化优先的媒体整理入库平台，单管理员、全局偏好、四站优先；完整控制台与 Pi Agent 共同通过 API/MCP 使用业务能力。标签纳管 qB，用户可主动授权更广调查与操作。常规自动执行不反复审批，默认不自动换源。

媒体采用本地身份、稳定路径与独立版本目标。当前收藏偏好为适用范围内优质 1080p/4K 蓝光压制，特殊边界交给 Agent；综艺按正片覆盖判断完整，附加内容可配置。旧库先登记再按范围开启管理。跨季使用 TMDB、本地模糊召回和 Agent，人工映射优先，候选不污染正式库。

站点独立启停、快照缓存优先，PT 工作台提供整理视图和同会话原站接管；优先连接现有 camofox-browser，人工与 Agent 交接控制权。可选 Emby 兼容辅助查询；整理记录通过 API Key 公开，包含前后路径及文件级结果，外部自行适配。Copy/Move 与缓存清理遵守入库验证和 HR/保留要求；缓存硬阈值优先于下载任务优先级。

17.2 需要填写的部署配置（不是未决定产品方向）

HHWEB 所指站点的准确域名/身份；另外 1–2 个站点；实例地址和凭据；qB 标签；各容器路径及共享挂载；现有目录模板；实际电影/剧集/综艺 Slot 作用范围；Copy/Move 默认范围；HR/用户保留要求及单位；缓存阈值/恢复水位；新旧媒体保留策略；NFO/海报权限；快照周期；Pi 上游、思考档位、上下文/压缩预算与子代理开关；现有 camofox-browser 的仓库/版本、服务地址、认证及会话配置。

Move 遇未满足 HR 时采用等待还是已授权 Copy 回退、升级后旧文件何时清理、合并版是否替换既有分段，尚未指定唯一默认值。实现为可配置策略，不把示例当授权，也不让这几项阻塞其他独立链路。

17.3 技术方向与准入验证

项目	当前方向	验证后才能确定的内容
业务核心	TypeScript、Deno 最新稳定版优先	精确版本、npm/Node API 兼容、生产部署与依赖锁
数据库	PostgreSQL	驱动/查询层、迁移、索引与实际规模性能
执行引擎	OpenWorkflow 优先候选	Deno 兼容、等待/取消/重试、崩溃恢复与旧流程升级
Agent	Pi SDK，单套上游能力配置	会话/压缩 API、思考能力、子代理实现与隔离
前端/API	React/TanStack 候选，公开 REST/OpenAPI/MCP	Deno 服务端框架与 transport，不预设未经验证组合
浏览器	camofox-browser 优先，原站同会话可视化接管	固定 fork/版本、API 合同、持久会话、画面/输入交接；linuxserver/chrome 仅为可选参考，不默认两引擎串联
文件工具	ffprobe/MediaInfo、流式或文件系统搬运	真实挂载性能、目标冲突与恢复语义

不因使用框架而省略业务状态机，也不因参考项目自研而认定其不稳定。第一版无需同时实现两套执行引擎。Go/Rust、向量库、Redis/Kafka 等不作为默认前提，仅由实际瓶颈或必要能力推动。

17.4 下一阶段的具体产物

1. 两项目实现迁移对照：优先做 MP 元数据识别/刮削和视频文件转移入库的完整调用链，覆盖多文件、整季包、目标冲突与恢复，再覆盖 MovieClaw 扫描/告警/Agent 展示；给出对应 TS 模块、行为矩阵、可复现样本与保留/调整理由。
2. 固定版本的兼容性原型：Deno + Pi + PostgreSQL + MCP + OpenWorkflow，以及浏览器/媒体工具进程通信。
3. 一条由 Agent 发起并跟踪的完整恢复纵切：用户目标 → 库存/资源调查 → 提交 qB → 完成核验 → Copy/Move → 整理记录 → 保留等待 → 缓存清理；包含后台唤醒、用户离线、中断和升级验证。
4. 四站真实脱敏样本集：跨季召回、综艺分段、版本差异和误匹配案例；报告召回、误关联和积压，不只展示成功样例。
5. 正式接口与数据迁移草案：偏好标签、来源快照、外部库存、整理记录、授权/取消和旧库接入。
6. 可观测性合同：业务时间线、计数、根因告警、Agent 运行卡、整理记录和指标共用身份与状态投影（详见 13.4）。
7. PT 工作台原型：统一列表/详情/库存标注 → 统一下载入口 → camofox-browser 原站视图 → 人工/Agent 同会话交接；记录无法支持的能力及替代实现代价。

本版完成的是需求与架构基线整合。上述专项源码研究、兼容性原型和真实服务测试尚未完成，不以需求文档更新替代其验收。

17.5 首期范围边界

不做整库迁移、底层分支盘均衡、开放插件市场、自建播放器/转码平台、多用户独立偏好、媒体服务器收藏/播放记录同步、模型轻重档路由和默认自动换源。首期允许媒体级显式整理、多个服务实例、PT 工作台与同会话浏览器接管、授权 Agent 调查与可配置子代理；这些不能因范围收敛而被误删。

附录 A 参考来源与核验边界

以下均为官方项目仓库、官方文档或系统手册；访问日期为 2026-09-27。正文中的 [Sxx] 指向本表。项目能力描述依据文档，不代表本次进行了运行测试。设计建议与验收要求由本项目需求推导，不是引用项目已实现的承诺。

[S01] MoviePilot v3 README。核心流程、FastAPI/Vue、Agent/MCP 入口及 README 使用声明。
https://github.com/jxxghp/MoviePilot/blob/v3/README.md

[S02] MoviePilot V2 到 V3 版本变化总览。页面说明主要比较 V2.15.6 与 V3.0.0，内容同步至 2026-09-03；用于核对多来源身份、分类策略、路径快照和可靠执行，不作为后续全部版本的完整变更记录。
https://github.com/jxxghp/MoviePilot/blob/v3/docs/v2-to-v3-overview.md

[S03] MovieClaw README 与 Agent Skills 设计文档。用于目录接入、待识别、并行版本、CLI 和 Skills 思路对照。
https://github.com/movieclaw/movieclaw
https://github.com/movieclaw/movieclaw/blob/main/docs/design/agent-skills.md

[S04] Pi 官方仓库与 LICENSE。核对项目迁移、组件分层、权限边界及许可。
https://github.com/earendil-works/pi
https://github.com/earendil-works/pi/blob/main/LICENSE

[S05] Pi SDK 与 Agent Core README。核对会话、资源加载、工具控制和事件接口。
https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/sdk.md
https://github.com/earendil-works/pi/blob/main/packages/agent/README.md

[S06] Pi SDK Full Control 官方示例。用于验证显式替换配置和资源发现的能力；本文不照抄其示例开放工具。
https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/sdk/12-full-control.ts

[S07] OpenWorkflow 官方 Production 文档。PostgreSQL worker 架构、无独立协调服务器、部署及 Dashboard 认证边界。
https://openworkflow.dev/docs/production

[S08] OpenWorkflow ARCHITECTURE。工作流状态、执行步骤和 signal 的即时投递语义。
https://github.com/openworkflowdev/openworkflow/blob/main/ARCHITECTURE.md

[S09] Playwright Authentication。认证状态的安全、复用和 sessionStorage 限制。
https://playwright.dev/docs/auth

[S10] MoviePilot v3 LICENSE。具体复用必须核对拟用版本与关联文件的许可。
https://github.com/jxxghp/MoviePilot/blob/v3/LICENSE

[S11] MovieClaw main LICENSE。记录历史 MIT 与后续附加条款版本的边界。
https://github.com/movieclaw/movieclaw/blob/main/LICENSE

[S12] Linux link(2)。硬链接文件系统条件与错误边界。
https://man7.org/linux/man-pages/man2/link.2.html

[S13] Linux rename(2)。重命名原子性适用范围、跨挂载错误等。
https://man7.org/linux/man-pages/man2/rename.2.html

[S14] OpenWorkflow 官方仓库。项目入口及仓库列出的 Apache-2.0 许可信息；生产依赖以锁定版本为准。
https://github.com/openworkflowdev/openworkflow

[S15] Node.js 官方文件系统、流与 worker threads 文档。异步文件操作与线程池、流式缓冲及 CPU 任务边界；不代表本项目已做性能测试。 https://nodejs.org/api/fs.html https://nodejs.org/api/stream.html https://nodejs.org/api/worker_threads.html

[S16] 源码对照快照。只读检查，未运行服务；具体分析见配套《MoviePilot V3 与 MovieClaw 深度调研》。 https://github.com/jxxghp/MoviePilot/tree/33da9ce65d5020a8e087584a3321c1ff353c1921 https://github.com/movieclaw/movieclaw/tree/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90

[S17] Deno 官方 Node/npm 兼容性文档。用于说明 npm 与 Node API 支持及局部限制，不作为本项目依赖组合已测试的证明。 https://docs.deno.com/runtime/fundamentals/node/

[S18] camofox-browser 项目 README 与 OpenAPI。页面快照、截图、结构化提取和下载捕获等能力参考；用户实际部署可能为不同 fork，必须核对版本。本次仅查看文档，未连接浏览器服务。 https://github.com/jo-inc/camofox-browser/blob/master/README.md https://github.com/jo-inc/camofox-browser/blob/master/openapi.json

[S19] linuxserver/docker-chrome 项目 README。Chrome 远程交互、Selkies 画面传输、部署及认证边界；不是 Camoufox 会话前端。 https://github.com/linuxserver/docker-chrome

[S20] Camoufox 官方 Features 与 Python Interface。底层虚拟显示及浏览器接口能力，不能直接推定 camofox-browser 上层已经提供可视化接管。 https://camoufox.com/features/ https://camoufox.com/python/

[S21] MP 可观测性与执行展示证据（固定源码快照，只读核验）。 https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/db/models/transferhistory.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/application/dashboard.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/api/endpoints/dashboard.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/scheduler/progress.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/db/models/agenttaskrun.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/docs/agent.md https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/application/subscription/observability.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/adapters/observability/otel.py https://github.com/jxxghp/MoviePilot/blob/33da9ce65d5020a8e087584a3321c1ff353c1921/app/adapters/web/metrics.py

[S22] MovieClaw 活动中心、根因分组与诊断证据（实现与设计对读，未运行 UI）。 https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/docs/design/activity.md https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/lib/task-center.ts https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/lib/task-activity.ts https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/lib/job-attention.ts https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/components/task-center-view.tsx https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/src/movieclaw_api/services/download_health.py https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/src/movieclaw_api/services/diagnosis_handoff.py

[S23] MovieClaw Agent 过程、数据卡片和稳定会话排序的实现。 https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/components/agent-conversation-view.tsx https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/components/agent-media-cards.tsx https://github.com/movieclaw/movieclaw/blob/fc9eb7248dd9c4f7cd8f3fbd704a357b0b766b90/apps/web/lib/agent-activity.ts

附录 B 版本说明

• v0.1：初始需求与架构设想。

• v0.2：十轮需求确认、源码初步对照与自动化管理范围。

• v0.3：追加访谈收口；Deno/OpenWorkflow 方向、偏好标签、双版本策略、阈值、跨季召回、站点快照、Pi 配置、整理 API、Emby 辅助查询、单管理员及默认不换源；增补 MP 专项核验清单与验收场景。

• v0.4：本轮最终需求基线；整合 PT 站点工作台、结构化/原站双视图、camofox-browser 优先接入、人工/Agent 同会话交接；同步架构、实施阶段和 66 项验收场景。

• v0.5：内部使用与 Agent 自动化优先复审；修正 M1 的仅建议定位，明确受控执行工具、后台事件唤醒、持久目标闭环、结果核验与自动化效果指标；增加 MP/MovieClaw 可观测性源码复审与展示合同；共 80 项验收场景。

• v0.6：明确两项目源代码为主要实现参考，采用内部使用的 TS 业务逻辑迁移与适配方式；补充模块来源分工和迁移交付规范，消除“仅借鉴思想、全部从零实现”的歧义。

• v0.7：将 MP 元数据识别/刮削与视频文件转移入库明确为优先迁移专项，补齐研究链路、本项目适配边界及交付要求。

本 Markdown 为当前需求基线。早期 v0.1 Word 文档和独立调研报告是历史材料，未随本次同步改版；具体实现以本版确认行为和后续通过验证的技术决策为准。