CodePawl Video Lab

面向 CodePawl 的自托管、证据优先的 YouTube 分析。Chrome 扩展仅收集当前活跃的 YouTube URL 以及用户主动导入的数据。Cloudflare Worker 将档案和已授权频道的分析数据存储在 D1 中。Codex 通过无状态的 Streamable HTTP MCP 服务器读写分析；扩展内部不包含 LLM。

YouTube URL → Chrome side panel → Worker + D1 → /mcp → Codex
                                      ↑             │
                                      └── reports ──┘

工作区

apps/extension   WXT + React MV3 side panel and library
apps/worker      Cloudflare Worker, D1, Cron, Google OAuth and remote MCP
packages/contracts  shared Zod schemas, parsers and evidence rules
docs             architecture, security and approval-gated deployment notes

扩展没有内容脚本。其构建后的 manifest 仅请求 sidePanel、storage、activeTab 和 tabs；它不会检查 YouTube DOM、下载字幕，也不会访问视频/音频字节。

Related MCP server: yt-mcp

本地开发

要求：Node 22+、npm 12+、Chrome 114+。

git clone git@github.com:codepawl/codepawl-video-lab.git
cd codepawl-video-lab
npm ci
npm run cf:types
npm run db:migrate:local
npm run dev:worker
npm run dev:extension

将 apps/worker/.dev.vars.example 复制到已被 git 忽略的 .dev.vars，并且只填写本地凭据。将 TOKEN_ENCRYPTION_KEY 生成为 32 个随机字节，使用 base64 或 base64url 编码。本地开发的 Google OAuth 重定向 URI 为：

http://127.0.0.1:8787/oauth/youtube/callback

通过本地管理路由创建一个十分钟配对码，然后在侧边面板中输入该配对码。生成的扩展令牌将在 30 天后过期，并可通过 Ngắt thiết bị 撤销：

curl -X POST http://127.0.0.1:8787/api/v1/admin/pairing-codes \
  -H "Authorization: Bearer $LOCAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Chrome extension"}'

构建未打包的扩展：

npm run build --workspace @codepawl/video-lab-extension

然后在启用开发者模式的情况下，从 chrome://extensions 加载 apps/extension/.output/chrome-mv3。将其安装到个人 Chrome 配置文件中是有意为之的手动/需审批操作。

数据规则

• 参考视频：元数据和匿名化评论文本来自 YouTube Data API v3。评论只会短暂缓存；从不存储作者身份。

• 字幕：仅支持用户粘贴或导入 .srt、.vtt、.txt 文件。

• CodePawl：仅使用 youtube.readonly 和 yt-analytics.readonly。不存在上传、元数据编辑或发布权限范围。

• Stayed to watch：人工在 Studio 中观察，并带有明确的来源说明。它并不作为 Analytics API 指标来表示。

• 参考频道的留存率、CTR 和 Stayed to watch 从不被推断得出。

• 每项发现都必须指向带有来源、观察时间、置信度和局限性的证据。

• 公共 API 数据在 30 天后过期。Cron 首先尝试进行一次新的 API 观察；如果无法刷新，已过期的参考数据将被删除。

• Google 刷新令牌和访问令牌在持久化到 D1 之前会使用 AES-256-GCM 加密。

MCP

/mcp 是一个由 D1 支持的无状态 createMcpHandler 服务器。它提供：

• video_inbox_list

• video_dossier_get

• video_dossiers_compare

• channel_performance_get

• retention_curve_get

• analysis_report_save

• experiment_create

• experiment_update

资源：codepawl://rubrics/shorts-v1。

在生产环境中，Cloudflare Access Managed OAuth 保护 /mcp；Worker 独立验证 Access 断言的签发者、受众和 RS256 签名。完成部署和 Access 设置后：

codex mcp add codepawl-video-lab --url https://video-lab.codepawl.com/mcp
codex mcp login codepawl-video-lab

在每台需要连接已部署服务器的机器上运行这两条 codex mcp 命令。认证是按机器进行的；凭据和本地 Codex 配置不会存储在此仓库中。

跟踪

Cron 每 15 分钟运行一次，并通过已授权频道的上传播放列表发现新上传的视频。新视频会收到 2 小时、24 小时和 72 小时的真实未来目标，以及每日汇总。历史导入的数据在连接时获得一次初始观察，且永远不会收到伪造的追溯性里程碑时间戳。空的 Analytics 响应保持 pending 状态，并以有界退避进行重试。作业唯一键和快照约束使重复运行具有幂等性。

验证

npm run typecheck
npm test
npm run build
npm run db:migrate:local
npm run worker:dry-run

可视化测试夹具仅限本地使用：

cd apps/worker
npx wrangler d1 execute video-lab --local --file test/fixtures/visual-qa.sql
cd ../..
npm run visual:dev --workspace @codepawl/video-lab-extension

打开 http://127.0.0.1:4173/visual.html?surface=sidepanel；库则打开 visual.html。该测试工具使用夹具数据，并且不包含在 MV3 构建中。

审批边界

此仓库的设置不会创建任何 Cloudflare 资源、DNS 记录、Access 应用、Google OAuth 凭据或生产部署。有关需要单独审批的确切资源包，请参阅 docs/deployment.md。

许可证

MIT。参见 LICENSE。

主要参考

• Chrome Side Panel API

• YouTube Analytics metrics

• YouTube API developer policies

• YouTube Captions API

• Cloudflare stateless MCP handler

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Codex Streamable HTTP MCP