b100-yunxin — AI 操作手册

前置依赖：本 skill 的核心脚本位于 b100-downloader/scripts/，必须同时安装该 skill。 用户配置手册：首次使用前，引导用户阅读 references/setup-guide.md。

决策树：何时用这个 skill？

用户要处理 B100 录音
        │
        ├─ 有云信 AppKey + AppSecret？
        │         │
        │         YES → 用 b100-yunxin（本 skill）
        │               ✓ 说话人识别（讲话人1/2/3）
        │               ✓ 千问智能摘要
        │               ✓ 按主题自动重命名
        │
        └─ NO / 不知道 → 用 b100-downloader（本地 Whisper 转录）

执行流程

快速启动（一键）

# Claude Code
python .claude/skills/b100-yunxin/scripts/pipeline.py --backend yunxin --context "{会议背景}"
python .claude/skills/b100-yunxin/scripts/rename_by_theme.py

# OpenClaw（项目级）
python skills/b100-yunxin/scripts/pipeline.py --backend yunxin --context "{会议背景}"
python skills/b100-yunxin/scripts/rename_by_theme.py

所有脚本已打包在 b100-yunxin/scripts/ 下，无需依赖 b100-downloader 的目录。

分步执行（含 I/O 规范）

Step 1 — 下载录音

输入：B100 服务器（B100_SERVER_URL + 账号密码）
输出：{OUTPUT_DIR}/recordings/{设备SN}/*.m4a（零散小文件）

# Claude Code
python .claude/skills/b100-yunxin/scripts/b100_downloader.py --output-dir recordings
# OpenClaw
python skills/b100-yunxin/scripts/b100_downloader.py --output-dir recordings

Step 2 — 合并分组

输入：Step 1 输出的零散 .m4a 文件
输出：{OUTPUT_DIR}/recordings/{设备SN}/{日期}_{SN}_merged.m4a
规则：文件 ≥ 3.6MB 视为录制结束标记，触发合并

python .claude/skills/b100-yunxin/scripts/session_grouper.py recordings/{设备SN}

Step 3 — 转录（含 NOS 上传）

输入：*_merged.m4a
输出：云信任务 ID（结果异步回调）
摘要格式：general（通用模板，含对话概述/待办/智能章节/关键决策/金句时刻）
首次 NOS：自动弹出浏览器，用网易企业账号登录一次，Cookie 自动保存

python .claude/skills/b100-yunxin/scripts/yunxin_transcribe.py recordings/{设备SN} --batch \
  --context "{补充背景，如：内部会议，讨论产品方向}"

⚠️ 提交后进入等待阶段，pipeline.py 自动轮询 webhook.site 最多 10 分钟

Step 4 — 重命名（回调到达后）

输入：*_summary.md（云信回调写入）
输出：{主题}.txt + {主题}-摘要.md

python .claude/skills/b100-yunxin/scripts/rename_by_theme.py recordings

错误处理流程

错误现象	优先检查	解决方案
NOS 上传 401	Cookie 过期	重跑任意命令，会自动弹浏览器重新登录
NOS 上传 403	账号权限不足	联系管理员确认账号有 NOS 上传权限
云信提交 400	音频时长/格式	检查 `*_merged.m4a` 是否完整，≥1s 且为 AAC/M4A
10分钟无回调	抄送配置	检查云信控制台「音视频通话2.0」→「媒体处理事件统一抄送」是否已勾选
10分钟无回调	Webhook URL	确认 `YUNXIN_CALLBACK_URL` 不含 `#!/view/` 前缀
摘要为空	功能开通	云信控制台确认「音视频通话2.0」和「点播」均已开通
rename 未找到文件	转录未完成	确认 `*_summary.md` 存在后再运行 rename

输出结构

{OUTPUT_DIR}/recordings/{设备SN}/{YYYYMMDD}/
├── {日期}_{SN}_merged.m4a    ← 原始音频（保留，可溯源）
├── {日期}_{SN}_raw.json      ← 云信回调原始数据
├── {主题}.txt                ← 全文转录（说话人标注 + 时间戳）
└── {主题}-摘要.md            ← 结构化摘要（五大板块）

平台路径对照

平台	`{SCRIPTS}` 路径	`{SKILL_DIR}` 路径
Claude Code	`.claude/skills/b100-downloader/scripts`	`.claude/skills/b100-yunxin`
OpenClaw (项目级)	`skills/b100-downloader/scripts`	`skills/b100-yunxin`
OpenClaw (全局级)	`~/.openclaw/skills/b100-downloader/scripts`	`~/.openclaw/skills/b100-yunxin`

OpenClaw 执行时脚本路径可直接用相对路径，Claude Code 需要从项目根目录运行。

已知坑点（Self-annealing）

# 每次遇到新问题，在此追加，格式：
# - symptom: 现象
#   cause: 原因
#   fix: 修复方案

- symptom: "silence_remover 生成的文件比原文件大 2x"
  cause: "ffmpeg 重编码导致文件膨胀"
  fix: "yunxin 模式下已自动跳过本地静音处理，云信 API 自带预处理"

- symptom: "webhook.site 收到请求但 eventType 不是 602"
  cause: "勾选的抄送类型有误（选了 IM 或云端录制而非音视频通话2.0）"
  fix: "云信控制台重新配置，勾选「音视频通话2.0」→「媒体处理事件统一抄送」"

- symptom: "Webhook 地址校验返回 404"
  cause: "填写了浏览器地址栏的 #!/view/ URL 而非干净的 webhook 端点"
  fix: "从 webhook.site 页面顶部复制 URL，格式：https://webhook.site/{uuid}"

AI 操作规则

启动前检查（每次）：

读取 .env，验证 YUNXIN_APP_KEY、YUNXIN_APP_SECRET、YUNXIN_CALLBACK_URL 三项已填写
缺少任一项 → 停止执行，引导用户打开 references/setup-guide.md 按指引完成配置

背景信息收集： 提交转录前询问用户「这段录音的背景是什么（会议类型、参会人关系）？」，有则追加到 --context，能显著提升说话人角色推断准确率。

NOS 弹窗预告： 若 .env 中 NOS_COOKIE 为空，提前告知「系统即将弹出浏览器，请用网易企业账号登录一次，登录后直接关掉浏览器即可」。

等待期指引： 转录任务提交后，告知用户预计等待时间（短录音约 1-3 分钟，1小时+录音约 5-10 分钟），让用户知道正在等待而不是卡死。

超时处理： 10 分钟未收到回调 → 对照「错误处理流程」表，逐项引导用户排查。