机构文档更新器
自动按顺序执行所有步骤。仅在步骤失败且无法恢复时暂停。开始前请阅读 references/learnings.md 以了解已知陷阱。
配置:路径从技能根目录的 .env 文件中读取(参见 .env.example)。默认配置适用于标准设置。关键环境变量:VAULT_DIR、DOCS_SITE_DIR、YOUTUBE_UPLOADER_DIR、PRESENTATIONS_DIR、SKILLS_REPO_DIR、SKILLS_LOCAL_DIR、ZOOM_CREDENTIALS_DIR、GITHUB_REPO、SITE_DOMAIN。
依赖项(运行前请确认这些技能已安装):
- zoom — Zoom 录制下载 (
scripts/zoom_meetings.py) - fathom — Fathom 视频回退方案 (
scripts/download_video.py) - nano-banana — 缩略图叠加层生成 (
scripts/generate_image.sh) - calendar-sync — 仅本地,日历事件同步 (
sync.sh) - youtube-uploader — 视频处理、上传和 YouTube API 认证
步骤 0:解析参数并加载配置
从技能根目录加载 .env。然后按空白字符分割 args:
- 8位数字令牌 (
YYYYMMDD) →DATE - "yesterday" →
DATE = $(date -v-1d +%Y%m%d) - "today" 或缺失 →
DATE = $(date +%Y%m%d) - 2位数字令牌 (
NN) 或lab-NN→LAB_FILTER
展开用于后续步骤的路径环境变量:
VAULT_DIR="${VAULT_DIR:-$HOME/Brains/brain}"
DOCS_SITE_DIR="${DOCS_SITE_DIR:-$HOME/Sites/agency-docs}"
YOUTUBE_UPLOADER_DIR="${YOUTUBE_UPLOADER_DIR:-$HOME/ai_projects/youtube-uploader}"
SKILLS_REPO_DIR="${SKILLS_REPO_DIR:-$HOME/ai_projects/claude-skills}"
SKILLS_LOCAL_DIR="${SKILLS_LOCAL_DIR:-$HOME/.claude/skills}"
ZOOM_CREDENTIALS_DIR="${ZOOM_CREDENTIALS_DIR:-$HOME/.zoom_credentials}"
PRESENTATIONS_DIR="${PRESENTATIONS_DIR:-$HOME/ai_projects/claude-code-lab}"
GITHUB_REPO="${GITHUB_REPO:-glebis/agency-docs}"
SITE_DOMAIN="${SITE_DOMAIN:-agency-lab.glebkalinin.com}"
步骤 1:查找 Fathom 转录稿
如果设置了 LAB_FILTER:${VAULT_DIR}/${DATE}-claude-code-lab-${LAB_FILTER}.md
如果为空:使用通配符 ${VAULT_DIR}/${DATE}-claude-code-lab-*.md(选择最近修改的文件)。
如果文件缺失:运行 ${SKILLS_LOCAL_DIR}/calendar-sync/sync.sh,重新检查,如果仍然缺失则停止。
从 YAML 前置元数据中提取并存储:
FATHOM_FILE、SHARE_URL、MEETING_TITLE、DATE、LAB_NUMBERVIDEO_NAME=${DATE}-claude-code-lab-${LAB_NUMBER}TRANSCRIPT_LANG= 从前约50行自动检测(西里尔字母比例 > 0.3 →ru,否则en)
确定 MEETING_NUMBER:检查 ${DOCS_SITE_DIR}/content/docs/claude-code-internal-${LAB_NUMBER}/meetings/ 中现有的 MDX 文件,查找包含今天日期的占位符。如果找到,使用该编号。否则,检查文件内容大小以找到下一个空槽位。存储为零填充的两位数字符串(例如 04)。此变量用于步骤 3b、4b、5、6 和 8。
步骤 2:下载视频
如果 ${VAULT_DIR}/${VIDEO_NAME}.mp4 存在且大于 1MB,则跳过。
注意:会议结束后,Zoom 录制可能需要约15分钟处理。如果 Zoom API 返回无录制,则等待并重试,然后再回退到 Fathom。
主要方案 — Zoom:
python3 ${SKILLS_REPO_DIR}/zoom/scripts/zoom_meetings.py recordings \
--start ${DATE:0:4}-${DATE:4:2}-${DATE:6:2} \
--end $(date -j -v+1d -f %Y%m%d ${DATE} +%Y-%m-%d) \
--show-downloads 2>&1
找到 MP4 URL,然后:
TOK=$(python3 -c "import json,pathlib; print(json.load(open(pathlib.Path('${ZOOM_CREDENTIALS_DIR}')/'oauth_token.json'))['access_token'])")
curl -L -H "Authorization: Bearer ${TOK}" -o ${VAULT_DIR}/${VIDEO_NAME}.mp4 "${MP4_DOWNLOAD_URL}"
回退方案 — Fathom(如果没有 Zoom 录制):
cd ${VAULT_DIR} && python3 ${SKILLS_LOCAL_DIR}/fathom/scripts/download_video.py \
"${SHARE_URL}" --output-name "${VIDEO_NAME}"
步骤 3:上传到 YouTube
cd ${YOUTUBE_UPLOADER_DIR} && \
python3 process_video.py \
--video ${VAULT_DIR}/${VIDEO_NAME}.mp4 \
--fathom-transcript ${FATHOM_FILE} \
--title "${MEETING_TITLE}" \
--upload
使用 run_in_background: true 运行(10-30分钟)。如果失败:使用 --resume-from upload。
从标准输出(✓ YouTube video: ...)或 processed/metadata/${VIDEO_NAME}.json 中提取 YOUTUBE_URL。
从URL中提取 VIDEO_ID(?v= 之后的部分或最后路径段)。
步骤 3a:验证上传(必需)
提取 VIDEO_ID 后,在继续之前验证视频确实存在于 YouTube 上。视频可能会静默处理失败或因 YouTube 的内容审核被自动删除。
cd ${YOUTUBE_UPLOADER_DIR} && PYTHONPATH=. python3 -c "
from auth import get_authenticated_service
import sys, time
youtube = get_authenticated_service()
video_id = '${VIDEO_ID}'
# 轮询最多5分钟,等待视频可用
for attempt in range(10):
resp = youtube.videos().list(part='status,processingDetails', id=video_id).execute()
if not resp['items']:
if attempt < 9:
print(f'Video not yet available (attempt {attempt+1}/10), waiting 30s...')
time.sleep(30)
continue
print(f'FATAL: Video {video_id} not found after 5 minutes. Upload may have failed.')
sys.exit(1)
status = resp['items'][0]['status']
processing = resp['items'][0].get('processingDetails', {})
upload_status = status.get('uploadStatus', 'unknown')
privacy = status.get('privacyStatus', 'unknown')
rejection = status.get('rejectionReason', None)
print(f'Upload status: {upload_status}, Privacy: {privacy}')
if rejection:
print(f'REJECTED: {rejection}')
sys.exit(1)
if upload_status in ('processed', 'uploaded'):
print(f'✓ Video {video_id} verified OK')
sys.exit(0)
if upload_status == 'failed':
print(f'FATAL: Upload failed — {status.get("failureReason", "unknown")}')
sys.exit(1)
print(f'Status: {upload_status}, waiting 30s...')
time.sleep(30)
print('FATAL: Video not ready after 5 minutes')
sys.exit(1)
"
如果验证失败:删除失败视频的元数据(rm processed/metadata/${VIDEO_NAME}.json),使用 --resume-from upload 重新上传,并重新验证。在 VIDEO_ID 未经验证的情况下,不要继续执行 MDX 或缩略图步骤。
并行启动步骤 4 — 摘要不依赖于 YouTube URL。
步骤 3b:实验室风格缩略图(必需)
始终运行此步骤 — 它会替换 process_video.py 生成的通用缩略图,使用品牌化实验室模板。通用缩略图不适用于发布。
前提条件:必须知道 VIDEO_ID(如果需要,等待步骤 3 完成)。
遵循 references/thumbnail-guide.md 中的完整工作流程:
- 生成 Nano Banana 叠加图像(根据指南提示模式中的主题特定提示)
- 读取/检查原始图像以确认背景颜色,然后将线条重新着色为橙色 (#e85d04)
- 基于
${YOUTUBE_UPLOADER_DIR}/templates/images/lab-meeting.html编写一个 临时 HTML 文件(例如/tmp/lab-meeting-${MEETING_NUMBER}.html)—— 更新会议编号、主题主文本、项目符号描述、日期。不要原地编辑原始模板。 - 使用 Playwright 以 1280×720 渲染 →
${YOUTUBE_UPLOADER_DIR}/processed/thumbnails/${VIDEO_NAME}.jpg - 读取/检查渲染后的缩略图以在上传前验证布局
- 上传到 YouTube:使用步骤 3 中提取的
VIDEO_ID
不要跳过此步骤或依赖于 process_video.py 生成的缩略图。
步骤 4:生成事实核查摘要
读取 ${FATHOM_FILE}。生成结构化的摘要 使用 ${TRANSCRIPT_LANG}:
##节标题、项目符号、相关代码示例- 技术术语使用英文(MCP、Skills、Claude Code 等)
- 排除个人日程安排细节
- 为 MDX 进行清理:转义会破坏 MDX 编译的
<、>和裸{字符
使用 claude-code-guide 子智能体核查 Claude Code 功能声明的真实性(如果可用;如果无法访问该智能体,则跳过事实核查)。将修正后的摘要保存到 scratchpad 中,文件名为 summary.md。
步骤 4b:更新 YouTube 元数据
在步骤 3 和步骤 4 都完成后执行。 在此步骤之前必须确定 VIDEO_ID、MEETING_NUMBER 和 LAB_NUMBER。阅读 references/youtube-api.md 了解描述格式和 API 代码片段。
从摘要生成 YouTube 描述。使用语言对应的模板:
- 如果
TRANSCRIPT_LANG=en:英文标签("In this video:"、"Course materials and session notes:") - 如果
TRANSCRIPT_LANG=ru:俄文标签("В этом видео:"、"Материалы и конспект занятия:")
不要在单个描述中混合使用语言。
会议页面 URL:https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER}
通过 YouTube API 更新标题、描述、标签,然后将视频添加到播放列表 "Claude Code Lab ${LAB_NUMBER}"(如果不存在则自动创建)。
步骤 5:生成 MDX
python3 ${SKILLS_LOCAL_DIR}/agency-docs-updater/scripts/update_meeting_doc.py \
${FATHOM_FILE} "${YOUTUBE_URL}" ${SCRATCHPAD}/summary.md
运行前:检查是否存在针对今天日期的占位符 MDX 文件(在 meetings/ 中使用 grep -l)。如果存在,使用 -n ${MEETING_NUMBER} --update 来定位它。
运行后:
- 剥离附加的 Marp 内容(摘要关闭
---和<!-- _class: lead -->之间的所有内容)—— MDX 在 HTML 注释 (<!-- -->)、未转义的<和裸{字符上会出错 - 检查演示文稿文件:在
${PRESENTATIONS_DIR}/presentations/lab-${LAB_NUMBER}/和${PRESENTATIONS_DIR}/lesson-generator/中查找包含${DATE}的文件。如果找到,复制到${DOCS_SITE_DIR}/public/${DATE}-claude-code-lab-${LAB_NUMBER}.html,并在 MDX 中添加链接 - 替换前置元数据占位符(
[Название встречи]、[Краткое описание встречи]、[Дата встречи]) - 如果
TRANSCRIPT_LANG=en,用英文标签完全重写 MDX —— 脚本默认使用俄语,且翻译回退会产生损坏的混合语言输出 - 验证:
cd ${DOCS_SITE_DIR} && npm run build 2>&1 | tail -5
步骤 6:提交并推送
只暂存管道文件 —— 从不使用 git add .:
cd ${DOCS_SITE_DIR}
git fetch origin main
BEHIND=$(git rev-list --count HEAD..origin/main)
if [ "$BEHIND" -gt 0 ]; then
git stash push -m "agency-docs-updater: temp stash"
git pull --rebase origin main
git stash pop || true
fi
git add content/docs/claude-code-internal-${LAB_NUMBER}/meetings/${MEETING_NUMBER}.mdx
# 仅当演示文稿 HTML 被复制时才暂存
[ -f public/${DATE}-claude-code-lab-${LAB_NUMBER}.html ] && git add public/${DATE}-claude-code-lab-${LAB_NUMBER}.html
git commit -m "Add Lab ${LAB_NUMBER} Meeting ${MEETING_NUMBER}"
git push
为步骤 7 存储 COMMIT_HASH=$(git rev-parse HEAD)。
步骤 7:等待 Vercel 部署
TIMEOUT=300; ELAPSED=0
until [ "$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state' 2>/dev/null || echo 'pending')" != "pending" ]; do
sleep 15; ELAPSED=$((ELAPSED+15))
[ "$ELAPSED" -ge "$TIMEOUT" ] && echo "Deploy timeout after ${TIMEOUT}s" && break
done
DEPLOY_STATE=$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state')
echo "Deploy state: ${DEPLOY_STATE}"
使用 run_in_background: true 运行。如果状态为 failure 或 error:检查 Vercel 日志(vercel logs),在本地修复,重新推送,重新启动此步骤。
步骤 8:在浏览器中验证
在浏览器中打开 https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER}(通过 chrome 自动化工具或手动)。验证 YouTube 嵌入是否可见。如果不可见:检查 VIDEO_ID,等待 YouTube 处理,或重新上传。
管道报告
完成后,报告:Fathom 路径、视频路径、YouTube URL、MDX 路径、提交哈希、部署状态、嵌入验证结果。