自托管的素材获取与分析工作站。 导入有权使用的视频与文档，调用内置 Skill，核对依据并导出 Markdown / DOCX 报告。
界面预览 · 快速开始 · 首次使用 · 从素材到报告 · 内置 Skill · 使用范围 · 设计文档 · English
下载记录：查看素材、处理状态与下一步操作。
查看素材入口、文档阅读与报告演示
素材入口。 从链接、本地视频或已有文档开始。
文档阅读。 阅读规范化文本与场景，再选择相容的分析方法。
分析报告。 核对结论、来源时间与引用，导出 Markdown / DOCX。
截图来自 2026-10-03 的已发布 Electron Renderer 演示构建，展示 Web／桌面共享页面；素材、任务与报告均为演示数据，不含真实账户或私人素材。当前主分支的界面可能有所调整；截图不代表平台下载、模型分析或客户端安装已经验收，实际边界见执行计划。
面向创作者、内容研究者和开发者，帧取把自己的素材与报告放在同一工作站。本仓库提供 FastAPI 接口、Next.js Web 工作区与后台处理；桌面端和 App 连接同一服务。
- 接入素材：按平台实际能力获取有权使用的媒体，也可导入自己的 MP4 与已有文档。
- 核对依据：视频观察关联抽样帧和源时间，文本分析关联原文单元与引用；模型结论需要对照来源核查。
- 留下报告：阅读并导出 Markdown / DOCX，重复导出复用已保存结果，不再次调用模型。
- 控制工作站：自行配置基础设施、存储与模型；各端共享账户、素材和任务。
只维护两份 Compose：docker-compose.yml 完整定义业务服务，本机与生产共用；docker-compose-env.yml 独立提供 PostgreSQL、RabbitMQ、Redis 和 MinIO。已有基础服务直接复用；仅在没有现成服务的环境显式运行 docker compose -f docker-compose-env.yml up -d --wait，再把业务配置中的 *_HOST／*_PORT 指向其实际地址与发布端口。Temporal 单独提供。先部署 Server，再让浏览器、Electron 或 App 连接。平台身份按 Registry 声明从普通 Chrome 扩展取得，接入方法见下文。
业务 Compose 项目名为 framefetch，后端镜像为 framefetch:local。runner_work 与 browser_profiles 默认绑定现有持久卷 video-server_runner_work、video-server_browser_profiles，保留任务文件与浏览器会话；其他卷名可通过 RUNNER_WORK_VOLUME_NAME、BROWSER_PROFILES_VOLUME_NAME 指定。数据库、队列、对象存储与鉴权标识保持其现有配置。
- Docker Engine 与 Docker Compose
- 本机已运行 PostgreSQL、RabbitMQ、Redis、MinIO 和 Temporal，已有配置直接复用
- 用于生产部署时，需要自行提供强随机密钥和公开访问地址
git clone https://github.com/StephenQiu30/framefetch-server.git
cd framefetch-server
test -f .env || cp .env.example .env
# 确认 .env 连接本机已运行的 PostgreSQL、RabbitMQ、Redis、MinIO 与 Temporal
# 启动：migrate 容器先应用幂等的 backend/sql/schema.sql，其余服务随后启动
docker compose up -d --build --wait --remove-orphans已安装宿主平台身份时，安装流程会生成私有的 .local-runtime/identity/runner.env；正常 Compose 启动、重建和 watch 会自动把其中的 Runner Bearer 注入 session-runner，无需额外命令或手动导出环境变量。首次安装与升级步骤见平台身份与升级。未安装身份时该文件可缺省，匿名平台正常运行。
开发时使用 docker compose up --build --watch，或在已启动的本地容器上运行 docker compose watch --no-up 并保持终端运行。前端代码自动热重载，API／worker 源码自动同步并重启，Runner 保留只读沙箱并自动重建；依赖变化自动构建。本地与 CI 使用已验证的 Docker Compose 5.5.1，详见 开发与发布规则。生产部署使用同一文件，配置方式见下方生产入口。
产品需求、系统设计与执行计划统一维护在 docs/。将该目录作为 Obsidian 库打开，或用任意文本编辑器修改；版本通过 Git 管理，详见 文档工作区。
启动后访问 Web 工作区、Swagger UI 或 OpenAPI。全新空库须先按下文创建首管理员，再登录使用。
所有容器化后台循环（Outbox 投递、解析与下载、导入、报告发布）运行在一个 worker 容器中，使用 RABBITMQ_WORKER_USER / RABBITMQ_WORKER_PASS。该账号须对 RABBITMQ_VHOST 中的当前业务队列有受限的 configure/write/read 权限；队列职责见可靠性与运行。平台身份安装见下文。
全新空库还没有登录账号时，在部署机终端执行一次首管理员初始化（需使用可连接 PostgreSQL 的 DATABASE_URL，密码交互输入，不进入命令行历史）：
uv run --project backend python -m app.workers.bootstrap_admin \
--env-file .env --username your-admin --email you@example.com命令只在用户表为空时创建管理员；已有任何用户时拒绝，不开放 HTTP 初始化接口。若要让其他用户自行注册，先在 .env 配置真实 SMTP 并启用 SMTP_ENABLED=true。健康检查只证明服务可运行，不证明每个平台有真实媒体证据。
- 登录后，在首页选择「剧本文档」，上传自己的 DOCX、PDF、TXT、Markdown 或 Fountain 文件。
- 在「剧本文档」列表核对导入状态；打开文档详情阅读正文与场景。下载记录、文档和管理列表会按屏幕宽度调整，窄屏将辅助信息并入记录摘要。
- 需要分析时，再按下文启用宿主 AI Worker；在素材详情选择 Skill、输出语言与提示词，完成后核对报告依据并导出 MD／DOCX。
仅查看和管理导入素材不需要调用模型；平台链接下载的身份与网络条件见使用范围。
Temporal、固定出口与住宅节点配置
解析与 Skill 分析连接宿主机已运行的 Temporal。docker-compose.yml 只启动业务服务；容器 Worker 通过 TEMPORAL_HOST／TEMPORAL_PORT 连接已有服务，默认 host.docker.internal:7233。CLI 与宿主 AI Worker 使用 TEMPORAL_ADDRESS，默认 127.0.0.1:7233。已有部署使用其他地址时设置对应连接参数，工作进程首次连接时幂等创建 TEMPORAL_NAMESPACE（默认 framefetch）。
更新前停止 API 接单并排空解析任务，备份现有业务库，再配套发布 API、worker 和 migrate 容器。更新使用 up --build，不能只 start 旧版已退出的迁移容器。回退也需先排空新执行并恢复匹配的结构备份，不允许两套解析执行者并存。
Temporal 的存储与备份由现有服务管理，项目重启只重启业务容器。Temporal 停机期间任务暂停；端口健康不等于平台可以下载。报告发布、下载与导入长期使用 RabbitMQ，分工见工作流设计。
Runner、yt-dlp、媒体 HTTP/FFmpeg、浏览器与 IP 观测共用 EgressBinding 的代理地址。Squid 的 3128 监听固定为 cn_residential，3129 固定为 global_residential；宿主对应 127.0.0.1:13128、127.0.0.1:13129。平台选择由 Registry 决定，Generic 直链按 .cn 域名选择国内路由，其余走境外路由。
部署者应自行取得静态 ISP/住宅节点，在宿主 Clash/Mihomo 中定义两个固定 HTTP 入站，分别绑定国内家宽出口与境外住宅节点。不要使用自动测速、负载均衡或会自动切换节点的组；解析与下载必须使用同一节点。先导入供应商提供的住宅节点订阅，或按供应商协议新增节点并命名为 GLOBAL-ISP。例如 SOCKS5 住宅节点的宿主配置如下；地址、端口和凭据由供应商提供，示例值只是占位符，不能写入本仓库或 Framefetch 环境变量：
proxies:
- name: GLOBAL-ISP
type: socks5
server: isp-global.example
port: 1080
username: 替换为供应商用户名
password: 替换为供应商密码协议字段见 Mihomo SOCKS 官方文档。国内节点可同样命名为 CN-ISP；本机本身就是国内家宽时，使用 DIRECT。两个入站绑定如下：
listeners:
- name: framefetch-cn
type: http
listen: 0.0.0.0
port: 17897
proxy: CN-ISP
- name: framefetch-global
type: http
listen: 0.0.0.0
port: 17898
proxy: GLOBAL-ISPproxy 将该入站全部请求固定交给指定节点，包含媒体 CDN 和 IP 回显服务，避免按目标域名分流导致观测 IP 与媒体出口不一致。也可以使用入站专用 rule 与最终 MATCH 规则。字段含义见 Mihomo Listener 官方文档。上游连接优先解析 IPv4，避免容器没有 IPv6 路由时被宿主 AAAA 地址阻断；仅有 IPv6 时保留主机名解析。监听须允许 Docker Desktop 访问，并由宿主防火墙限制为本机/Docker 来源。
在部署环境文件中设置 EGRESS_CN_UPSTREAM_HOST=host.docker.internal、EGRESS_CN_UPSTREAM_PORT=17897、EGRESS_GLOBAL_UPSTREAM_HOST=host.docker.internal、EGRESS_GLOBAL_UPSTREAM_PORT=17898。如本机本身就是国内家宽，可将国内 Listener 的 proxy 设为 DIRECT；未设置国内上游时，Squid 保留现有直连，并标记 egress_class=unknown：宿主 TUN 可能按目标域名分流，不能把这一路径冒充固定住宅节点。residential 表示部署者对该固定节点的类别声明，并非 IP 回显服务认证。
没有境外住宅节点时，EGRESS_GLOBAL_UPSTREAM_HOST 保持空值，境外路由使用 EGRESS_FALLBACK_UPSTREAM_HOST/PORT（默认宿主 Clash 7897），诊断标记 egress_class=datacenter。此状态仅供降级运行，YouTube 的住宅出口验收仍为阻塞。现有境外上游必须把该路由的全部流量（包括 IP 回显服务）固定到同一境外节点。
配置或 Clash 节点/规则改变后递增 EGRESS_NODE_REVISION，重建更新 egress-proxy 与 session-runner。Runner 计算有效路由配置的 SHA-256 修订摘要；下载前比较修订与观测 IP，变化时返回 context_changed，需要重新解析和确认。IP 回显按路由选择：国内默认 https://ip.3322.net，境外默认 https://ipinfo.io/ip，分别由 RUNNER_CN_EGRESS_IP_ECHO_URL、RUNNER_GLOBAL_EGRESS_IP_ECHO_URL 覆盖，服务须返回纯文本公网 IP。国内回显目标需保持在国内，避免宿主 Clash 按域名分流到境外节点而误报；回显仅代表该目标的观测，固定节点仍需上述 Listener 配置保证。缓存键包含路由、修订与回显地址；经同一路由请求，限时五秒、响应最多 128 字节、不跟随重定向，成功或失败均缓存十分钟。失败时 IP 为空，任务继续运行；不会用空值证明节点未改变。
平台身份安装、权限与升级
宿主身份服务位于 backend/app/workers/identity/，扩展源码位于 extension/，遵循平台身份设计。macOS 使用普通用户 LaunchAgent，Windows 使用当前用户计划任务；服务只监听 127.0.0.1:19101。WebSocket /extension 校验固定扩展 Origin 与双向 HMAC，POST /cookies 和固定 POST /yuanbao-parse 只接受 Runner Bearer。扩展先认证服务端，再按声明来源读取当前普通 Profile 的非分区 Cookie，或在 Service Worker 内执行固定元宝 HTTP 解析请求；Cookie 获取上限 5 秒，元宝解析上限 30 秒，均受操作截止时间约束，不建立材料库。无扩展连接、超时、无必要账号材料分别返回 extension_disconnected、extension_timeout、credential_missing，Runner 保留这些子因。视频号的 HTTP 请求桥已接入，专属解析与下载状态见视频号元宝解析。
从 backend/ 执行一次安装：
uv run python -m app.workers.identity.cli install
uv run python -m app.workers.identity.cli checkinstall 生成独立配对密钥和 Runner Bearer。macOS 配置默认为 ~/Library/Application Support/Framefetch/identity.env，Windows 为 %LOCALAPPDATA%\Framefetch\identity\identity.env；也可用 --env-file 指定已有独立私有身份配置，保留其 Runner Bearer 并补建配对密钥。已有安装升级会保留两份密钥，只更新项目目录内的生成文件并重启本服务。不得把项目 .env 当作宿主身份配置。macOS 注册 gui/<uid> 下的普通 LaunchAgent，不要求 Aqua 会话、钥匙串授权或完全磁盘访问；Windows 注册 FramefetchIdentityService，在当前用户登录时通过虚拟环境的 pythonw.exe 隐藏运行，使用交互用户令牌和最低权限，失败后自动重启。服务依赖此 checkout 的 backend 与 uv 虚拟环境，不要删除它们。uninstall 只停止并移除本服务，保留配对文件以便重装；遇到同名的其他服务拒绝覆盖。
先执行 install，再在 Chrome 加载扩展。manifest.template.json 是源码模板，Chrome 需要生成后的 manifest.json；出现“清单文件缺失或不可读取”时，确认安装命令成功，再点击“重试”或重新选择扩展目录。
在 Chrome 扩展页加载主工作区的 extension/（必须是绝对路径）。只加载到日常登录的一个普通 Profile；扩展申请 cookies、alarms、declarativeNetRequestWithHostAccess，host 权限限定 Registry 的 Cookie 域、视频号精确 https://yuanbao.tencent.com/* 与本机 WebSocket，不申请 scripting、广泛 tabs 或历史权限。1.3.3 的视频号解析在 Service Worker 内部通过固定 HTTP 接口完成：按解析接口 URL 读取当前 Profile 的 hy_user／hy_token，认证头及 Cookie 留在 Chrome，不导出给宿主或 Runner，不缓存凭据。打包的声明式规则仅将本扩展对固定元宝解析接口的 POST 请求 Origin 设置为元宝官网，补齐服务端来源校验所需的请求头；规则不匹配网页、其他扩展、其他接口或方法，不修改响应头。解析前确认规则集启用，否则在读取凭据之前终止。新增的是请求头修改能力，未扩大站点权限；升级时需要用户知悉并启用这一能力。解析与下载重解析均无需打开元宝页面，不执行页面脚本，也没有页面回退分支；账号切换、期限、重定向与响应大小均受校验。首次登录或登录过期时，通过面板“登录元宝”完成正常登录，再关闭页面即可。面板显示实际版本、连接、登录材料可用性及最近一次解析子因；材料可用不代表账号仍获服务端认可。加载后 check 报告实际连接状态与版本；Chrome 停止或尚未加载时显示 connected=false、version=null。升级后从主工作区重新执行 install，再在 Chrome 扩展页点一次“重新加载”。不要从 git worktree 加载；install 自动定位主工作区，宿主服务也使用主工作区的 backend。
macOS 扩展目录 0700、生成文件 0600；Windows 使用当前用户所有的 ACL，仅允许当前用户与 SYSTEM 访问。Windows 在写入密钥前收紧空文件的权限，读取或升级配置前检查访问规则，拒绝符号链接和目录联接。密钥和端口仅写入项目扩展目录的 config.local.json；它和生成的 manifest.json 均被 gitignore，安装会检查两者未被 Git 跟踪。源码只维护 manifest.template.json，不在 web_accessible_resources 中、不进入源码或发行包。信任边界：这些权限隔离网页与其他用户，不能隔离同一用户下可读写该目录的恶意进程。扩展和 cookie-source 共享配对密钥；Runner Bearer 是另一份独立凭据，不能复用。双向 HMAC 防止无配对密钥的本机假服务骗取 Cookie；不会赋予内容导出权利或扩大 content_scope。
Compose 仅向 session-runner 加载 .local-runtime/identity/runner.env。该文件由 install 与宿主服务 run 根据独立身份配置生成，只包含 COOKIE_SOURCE_TOKEN；API、worker、egress-proxy 和 bgutil 不持有它。目录与文件使用当前用户私有权限，写入时原子替换，生成前检查路径未被 Git 跟踪且已忽略；不打印令牌、不改写项目 .env 或 .env.prod。配对密钥不写入此文件，也不进入任何容器。不要把整个宿主身份配置作为容器 env_file。
普通 docker compose up、up --build、--force-recreate 和 watch 都读取同一专用文件，不依赖启动终端的 COOKIE_SOURCE_TOKEN。已有安装升级只需正常执行一次 install 更新宿主服务与生成文件，之后重建无需额外操作。该文件缺省表示未安装身份；需要 Chrome 身份的平台仍须完成上面的安装与连接。文件含独立 Runner Bearer，不应上传、提交或放入发行包，勿输出完整 docker compose config／docker inspect 的环境内容。
当前 Compose 与 squid 配套固定使用端口 19101，调整端口须同步精确代理 ACL。Runner 身份客户端显式使用受控代理，不使用环境代理、不跟随重定向；squid 只放行该宿主端口的 POST /cookies 和 POST /yuanbao-parse，强制直连，不经过 Clash／住宅上游。其他宿主端口、私网和 IP 字面量仍被拒绝。身份传输是明文 HTTP，egress-proxy 属于敏感信任组件，配置关闭访问日志、缓存和响应体存储。安装只启动宿主服务；业务服务仍由唯一的 docker-compose.yml 启动。
扩展使用 20 秒心跳、30 秒 alarm 和上限 30 秒的指数退避，并同步注册启动事件。保活机制依据 Chrome WebSocket 文档；真实关闭 DevTools、睡眠唤醒与各类重启恢复仍须实测。
Runner 身份调用、RunContext 材料所有权和私有 tmpfs 清理统一见平台身份与解析引擎第 10 节。真实 Chrome 保活、重连与需要身份的完整文件验收状态见验证状态。
升级前暂停接单并排空媒体操作，备份业务库，幂等执行当前 schema.sql，再配套重建 API、worker、session-runner 与前端。生产配置使用 .env.prod，设置 APP_ENV=production、FRONTEND_BUILD_TARGET=runtime、实际 SITE_URL 与生产密钥；前端运行环境和启动命令由 Dockerfile 的 runtime 阶段提供。生产入口：
APP_ENV=production FRONTEND_BUILD_TARGET=runtime docker compose --env-file .env.prod up -d --build --wait --remove-orphans健康检查：
curl --fail http://127.0.0.1:8111/health/live
curl --fail http://127.0.0.1:8111/health/ready
curl --fail --head http://127.0.0.1:8101/只需要下载与剧本文档导入时，可在 .env 中设置 ANALYSIS_ENABLED=false。完整的启动、停止、已有基础环境复用和故障恢复方式见可靠性与运行。更新代码时先执行 git pull --ff-only，再按上面的命令构建启动 Compose；docker compose restart 不会应用新代码、镜像或环境配置。
启用宿主 AI Worker
AI Worker 独立运行，不包含在业务 Compose 中。默认线路可以复用宿主机已登录的 Codex App Server；管理员也可在 Web 中配置受支持的模型 Provider。宿主机 Agent 的统一管理入口为：
cd backend
uv sync --frozen --dev
uv run python -m app.workers.analysis.agent_cli doctor
uv run python -m app.workers.analysis.agent_cli install
uv run python -m app.workers.analysis.agent_cli status生产业务使用 .env.prod 时，宿主机 Agent 必须读取同一环境文件：
uv run python -m app.workers.analysis.agent_cli doctor --env-file ../.env.prod
uv run python -m app.workers.analysis.agent_cli install --env-file ../.env.prod不要把 Codex/Claude OAuth 目录复制或挂载进容器。启用第三方模型前，请使用已获授权样本完成一次真实分析验收，并确认模型服务条款和组织数据策略。
- 接入：粘贴单条媒体链接或含单条链接的分享文案，按平台实际能力处理视频、图集或有限视频合集；也可上传 MP4，或导入五种格式的剧本文档。公众号文章仅做来源发现；当前候选不提供下载格式，页面提示官方播放或合法文件导入。
- 确认：链接解析展示媒体信息、访问决策和真实格式；视频按画质、容器、编码与音轨选择输出，图集与合集核对条目数量并确认 ZIP 下载。过期解析结果可以显式刷新，格式变化时重新确认。
- 获取：下载与导入在后台执行，页面显示排队、进度与结果，支持取消、重试和历史找回。本地视频采用受限分片上传，完成后由 Worker 复验。
- 管理：视频保存为经校验的制品，提供详情、预览与文件交付；图集和有限视频合集交付原图／视频 ZIP，包内
manifest.json记录标题、媒体类型与条目数量；剧本保存原件与规范化场景文本。任务、文件与报告在各端使用同一服务数据。 - 分析与整理：在原视频、文档详情选择内置 Skill，设置原语言与提示词后提交。处理失败不改变素材获取成功。
- 交付：阅读报告并核对来源与依据，导出 MD／DOCX。导出失败单独重做，复用已保存结果，不重新调用模型。
Web 工作区提供解析详情、下载记录、个人处理记录、视频播放、剧本阅读、分析与报告、平台状态及账户设置。快捷操作支持 ⌘K／Ctrl+K；页面提供明暗主题、键盘操作与适配窄屏的布局。活动任务通过 WebSocket 事件更新，重连时重新同步服务端事实。
管理员可以管理用户、文件、平台目录和 AI 服务，查看下载／AI 统计与系统操作日志。文件和报告持久保存，短时访问地址过期不会删除文件；删除和容量清理是显式操作。
在视频或文档详情选择适用的分析方法，设置中文／英文输出，编辑默认提示词或恢复默认。报告保留来源、依据、覆盖范围与限制，导出直接读取已保存结果。
视频审阅、分镜拆解与剧本文本分析用于核对现有素材；文章、公众号和小红书整理处理已有正文，并保留事实、引用、代码和链接。模型结论需要与原始来源对照核查。
可用方法以服务端返回的目录为准。产品范围见需求索引，真实样本、文件交付和客户端验证边界见执行计划。
- Server / Web：浏览器工作区、统一 FastAPI 接口、后台处理、存储、报告与管理。
- Electron 桌面端：复用 Web 业务页面，提供原生窗口、菜单、按服务地址隔离的会话和系统文件保存。
- Flutter App：iOS／Android 原生文件选择、播放、报告阅读、保存与分享。
各端连接同一 Server，原件、规范化文本和报告保存在部署者配置的服务端存储中。媒体处理由服务端执行，AI 分析由宿主 Worker 执行；桌面和手机不需要另建业务库，也不在客户端运行媒体提取器或离线模型。
帧取处于公开预览阶段。CI 验证确定性的工程检查；平台完整文件、真实模型、App 真机和桌面业务流程需要各自的验收证据。平台注册、解析成功和界面截图不能替代这些验证。
- 处理你有权获取和分析的 HTTP(S) 非 DRM 素材。平台接入包括 YouTube、哔哩哔哩、抖音、TikTok、小红书、快手、微博等；具体链接受内容范围、账号、网络和平台变化影响。视频号支持下载微信官方非加密分享文件，需要 Chrome 中已有有效元宝登录，无需打开元宝页面；公众号文章提供来源发现。准确平台状态与完整文件证据见 验证状态。
- 提供自托管源码与构建方式。服务器、基础服务、存储、网络和模型由部署者准备，外部模型可能计费；启用外部 AI 会向选定服务发送分析所需的文本或画面。
- 当前能力覆盖素材获取、管理、内置 Skill 分析／文档整理和报告。方法及输出的真实样本验收见执行计划，不能仅机械换行或截取正文开头就视为整理完成；模型分析须核查。内容写作、剧本改写、图卡制作、ASR／OCR、剪辑和账号发布不在本轮范围内。
- 成功素材和报告持久保存，管理员应规划容量、备份与显式清理。详细安全要求见 安全策略与解析设计；对外部署前替换占位配置并核对网络、存储与模型服务。
三个仓库的公开预览连接同一 Server：
| 项目 | 当前预览 | 发行内容 |
|---|---|---|
| Server / Web | v0.3.0-beta.2 | 自托管源码与 Compose 部署方式 |
| App | v0.2.0-beta.1 | iOS／Android 源码；未附 APK、IPA 或商店安装包 |
| Desktop | v0.2.0-beta.1 | macOS Apple Silicon DMG、Windows x64 安装包与 SHA-256 清单 |
这些版本均为 Beta 预览。桌面安装包未签名，macOS 未公证；干净安装、升级与真实 Server 完整业务需要独立验证。Git tag 标识发行快照：当前预览内嵌 Server/API/Worker 包版本仍为 0.2.0，App 为 0.1.0+1，桌面包为 0.2.0。部署相关组件时使用匹配源码与服务端契约，不能仅凭 tag 数字判断兼容性。
README 描述当前主分支；固定版本的安装、升级步骤和验证范围以对应 Release 与标签下 README 为准。
适用场景与技术架构
| 你的任务 | 帧取如何帮助 |
|---|---|
| 学习或复盘成片 | 核对候选切点、真实帧和源时间，补充人工观察与声音笔记 |
| 对照剧本与视频 | 使用固定剧本和抽样帧审阅候选对应、连续性问题与未覆盖范围 |
| 分析剧情与剧本 | 按固定原文单元分析人物、因果、节奏和问题，逐条核查引用与编辑建议 |
| 整理文章与渠道文档 | 直接处理已有正文和结构，保留代码、引文、链接与观点 |
| 建立个人工具链 | 使用自托管存储、可配置模型服务与 OpenAPI，扩展 Provider、方法或客户端 |
Web、Electron 和 Flutter App 共享同一 FastAPI 服务。客户端负责输入、交互与结果呈现；服务端负责身份、业务状态、媒体和文档处理、存储与报告，宿主 AI Worker 执行模型分析。
flowchart LR
Browser[Web 浏览器] --> Frontend[Next.js :8101]
Frontend --> API[FastAPI :8111]
Desktop[Electron / React] --> API
App[Flutter App] -->|Bearer API| API
API --> DB[(PostgreSQL)]
DB --> Outbox[Transactional Outbox]
Outbox --> Temporal[Temporal]
Temporal --> Resolve[Resolve Activity]
Resolve --> Runner
Outbox --> MQ[RabbitMQ]
MQ --> Download[Download Worker]
MQ --> Documents[Import / Report Workers]
Download --> Runner[隔离媒体 Runner]
Runner --> Proxy[受控出口]
Download --> Storage[(MinIO)]
Documents --> Storage
Temporal --> HostAI[宿主 AI Worker]
HostAI --> Storage
API -. WebSocket .-> Browser
| 技术 | 职责与用户价值 |
|---|---|
| Next.js、React、TypeScript、Tailwind CSS、Radix／shadcn | 浏览器工作区、可访问控件、响应式页面和结构化报告阅读；Electron 复用业务页面 |
| Python、FastAPI、Pydantic、OpenAPI | 提交、查询与取消任务，校验请求与结果，自动生成 REST 契约和客户端 |
| PostgreSQL、SQLAlchemy、Transactional Outbox | 在同一事务保存业务事实与执行意图，后台恢复依据持久状态 |
| Temporal、RabbitMQ | Temporal 编排解析与 Skill；RabbitMQ 处理下载、导入、报告发布和实时事件；长任务不阻塞 HTTP |
| yt-dlp、FFmpeg／ffprobe、Playwright、隔离 Runner | 适配平台差异、观察与处理媒体、核对完整文件；隔离媒体处理与请求进程 |
| MinIO、受限分片上传、短时授权地址 | 存储原件、视频与报告，支持大文件传输和授权取回 |
| Codex App Server、Claude CLI、HTTP 模型适配器 | 复用自备模型或已有宿主登录；方法与结果结构保持独立 |
| Flutter、Riverpod、Dio、media_kit | 原生移动输入、任务状态、播放、报告和系统分享；刷新凭据使用系统安全存储 |
| Electron、React、受控原生能力 | 原生桌面窗口、受控的文件操作与统一 Server 接入 |
| Redis、Docker Compose、独立宿主 AI Worker | 限流和短期运行状态，业务服务部署与恢复，媒体/AI 职责和凭据边界清晰 |
本机 Compose 复用已运行的 PostgreSQL、RabbitMQ、Redis、MinIO 和 Temporal；AI Worker 独立在宿主机运行。目录与生成契约规则见 PROJECT.md，完整设计见 文档索引。
前端需要 Node.js >=24.15 <25 与 pnpm 12，后端需要 Python >=3.12 <3.13 与 uv。代码级质量门禁：
cd backend
uv sync --frozen --dev
uv run --frozen ruff check app tests
uv run --frozen ruff format --check app tests
uv run --frozen mypy --strict app
uv run --frozen pytest -q
cd ../frontend
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm test
pnpm build仓库主要目录：
backend/ FastAPI、领域逻辑、Worker、Runner 与当前态 SQL
frontend/ Next.js App Router、业务组件、Hooks 与 OpenAPI 客户端
docs/ Obsidian 文档库（产品需求、系统设计与执行计划）
extension/ Chrome 平台身份扩展
backend/Dockerfile API、Worker、Runner 镜像
frontend/Dockerfile Next.js 独立镜像
docker-compose.yml 业务服务与可选开发监听，本机与生产共用
docker-compose-env.yml 独立基础设施，已有服务时不启动
平台支持与验证限制见解析引擎，其他未完成工作见BACKLOG，内置 Skill 实施及验证见PRD与执行计划。欢迎在 Issues 中讨论优先级，带有 good first issue / help wanted 标签的任务适合首次参与。
欢迎通过 Issue 或 Pull Request 参与 Provider 适配、可靠性、前端与移动端体验、AI 报告、测试和文档建设。开始前请阅读：
提交变更时，请保持实现、OpenAPI 契约、测试、运行手册和验收证据一致，并只提交小而完整、可独立验证的改动。
如果帧取对你的创作、研究或自托管实践有帮助，可以关注 Releases 获取版本更新，或在 Issues 提交具体反馈。
在论文、报告或课程材料中使用帧取时，可点击仓库侧栏的 “Cite this repository”，或直接使用根目录的 CITATION.cff。版本变更见 Releases。
Framefetch 基于 MIT License 开源。MIT 许可证授予软件使用、修改和分发权，不代表授予任何第三方媒体内容的下载、复制或分析权。
公开网站的索引配置、生成式搜索可发现性与上线核查见 Web 体验与 SEO。个人自托管实例默认不开放索引。
冷启动矩阵的两种模式、运行时锁、样本证据与文件校验用法见 Backend README。