raven-software-tutorial git:20260927.9df448dA

Immutable. This exact content never changes and is served at /api/v1/blob/6a84296fa3f82bd6.

---
name: raven-software-tutorial
description: 将已有软件录屏或可验证操作素材剪成教程、问题排查、功能演示与产品工作流视频，按教学或演示风格组织操作证据和旁白；仅要方案时交脚本，不把概念动画当实际操作。
---

# 软件演示与录屏教程

读 [共享作品合同](../../contracts/editorial-contract.md)。本 Skill 已有本地原子执行依赖；已有历史录屏及固定版本 miniPaint 的有限真实操作、受控参数修复证据；这些只覆盖声明的案例，完整语义观看、独立教学效果及原生剪辑宿主验收尚未完成。

## 先确定观众要学会或相信什么

区分学会操作、排查问题、理解原理、比较方案、观看功能发布。教程要能复现；宣传演示要使承诺有证据。用户只要“给这段录屏加字幕”时直接完成字幕，不自行重构故事或添加 CTA。

从当前素材获取软件版本、入口、受众知识、平台、目标任务、交付格式与不可变部分。风格缺项据目标选一版，不普遍要求脚本逐步审批。只在缺必要账号/可用素材/外部动作授权时暂停受影响步骤。

先确定交付模式与停止点：ANALYZE只交证据与判断，不自动写旁白或制作；PLAN交脚本、结构与声画参数计划，不提交作品或渲染；EDITABLE、PRODUCE和REVISION进入所要求的执行链。只要字幕时限定字幕对象、样式及必要的识别或映射，不增旁白、不重排步骤、不添加CTA；字幕文件与烧录成片按请求区分。参数齐全的烧录可直达原子，仍绑定要求修改的当前作品范围。

## 证据先于脚本

用 [media-inspect](../../atomic/media-inspect/SKILL.md) 固定素材身份；用 [frame-extract](../../atomic/frame-extract/SKILL.md) 检查重要操作前后及错误状态，并实际查看操作过程。遵循 [操作证据与教学规则](references/evidence-and-teaching.md)。网页/目录/菜单导航另读[导航教学](references/navigation-teaching.md)，区分历史教程、连续录屏和概念示意。逐步登记目标、前置条件、点击/输入、结果、验证方式和异常；截图能证明状态，不能独自证明该动作导致结果。

缺关键操作就补录或明确缺口；不根据旁白猜测按钮位置，不用生成界面补成真实过程。已有录屏优先使用；需新采集时依赖当前可用宿主，不假装库内已有 screen-record 原子。

新录制、导出或工程恢复类任务读[可复现操作素材](references/reproducible-capture.md)。固定软件版本和初始状态，分别核对实际界面、下载文件、空白页面重新打开及恢复结果；浏览器视窗录制不冒充完整操作系统录屏。

错误诊断与修复任务另读[排错教学](references/debugging-teaching.md)，分层登记修改与复验，不把最后成功归因给第一项修改。报错必须对应具体请求或步骤；favicon 404、旧终端日志和生成请求失败不能合并为同一故障。

## 风格决定信息组织

按 [软件风格索引](../../styles/software/index.md) 选主风格。教程、概念演示、结果预览和产品故事可借用声画手法，但保留各自的证明责任。短片可以减少支线，不能删掉决定成功的设置。用 [风格组合与评测](references/evaluation.md) 检查差异。

先做步骤依赖与声画表，再写旁白。每句回答当前看什么、为什么或如何判成功；不要把菜单名称逐个念一遍。已有讲解受原话和真实时长约束；新增 TTS 可调用 [tts-macos](../../atomic/tts-macos/SKILL.md)，但只在用户允许新增旁白且选择本地系统语音时使用，不替换已指定提供方。

## 编译与画面处理

在TaskSpec与教学计划中保留可审阅的决策记录：原Query或实际上下文来路、模式与停止条件、目标约束、机制选择与排除、步骤因果依据、源/输出时间映射和下一原子所需显式参数。已有记录可引用，不重复抄写；历史原Query未保留就明确缺项，不补造。提前展示的结果单独标“效果预览”，随后回到真实起点；预览不充当该步骤已经执行成功的证据。

将选段写入 ExecutionPlan，关键步骤填写 before/action/result 证据窗口、context_id、requires、阅读时长；调用 [tutorial-plan-compile](../../atomic/tutorial-plan-compile/SKILL.md)。合理的结果预览可以单独作为“效果预览”开场，不能伪装为当时执行成功。编译通过不证明标注真实，复杂层仍核对结果文案及源画面。

将编译计划、字幕、音轨、解释图层和教学决定放入[WorkDocument](../../contracts/work-contract.md)。新作品只初始化一次；已有作品先用[work-version](../../atomic/work-version/SKILL.md) read读取当前头，把计划合入当前文档，再用[timeline-revise](../../atomic/timeline-revise/SKILL.md)生成精确scope候选并commit；通过[work-render](../../atomic/work-render/SKILL.md)导出指定版本。独立片段试验可用[timeline-render](../../atomic/timeline-render/SKILL.md)，其成功不表示当前作品已更新。不同教学组织需保留父版时，用[work-variant-create](../../atomic/work-variant-create/SKILL.md)派生，而不是重建同名孤立作品。

放大或框选时由本层决定上下文保留范围，再调用 [screen-focus](../../atomic/screen-focus/SKILL.md)。静态聚焦不自动产生运动；多个区域需要切片分别处理并登记派生源，必要时保留全画面定位，避免跳切让观众失去方向。

源片先聚焦时沿用源时间；先剪辑再聚焦时使用成片时间。任何派生文件都重新登记哈希，不能把源片哈希套在新文件上。根据实际字号、视窗尺寸、字幕遮挡检查最终画面；横转竖不能机械 center-crop。

已有语音字幕先按完整语义分组，用 [caption-map](../../atomic/caption-map/SKILL.md) 映射；新增旁白以真实音频时长摆放，用 [audio-mix](../../atomic/audio-mix/SKILL.md) 和 [caption-burn](../../atomic/caption-burn/SKILL.md)。音乐可不加，不强行占据操作提示声。字幕不要盖住输入值、鼠标目标或结果反馈。

## 修改与交付

局部修改先read当前作品和历史，保留人工字幕、音轨、解释图层与已登记保护。单纯参数可以用[timeline-patch](../../atomic/timeline-patch/SKILL.md)生成计划，但仍须把计划合回当前文档，经timeline-revise→commit→work-render；不能用独立MP4覆盖同作状态。改变选段或时序需更新事件窗口并重新编译；教程证据图绑定计划，字幕/说明变更也要复核是否提前宣称结果。只更新允许范围；软件版本改变时核对菜单名和行为，不能只重新配音。

修改scope只开放实际变更字段；时序或来源变化需要同步调整的对象，记录其依赖与调整理由。仅需复核而无需修改的字幕、音轨与人工层保持冻结，不为了复核扩大写权限。

只采用某版的结果提示时，从该版提取对应字段合入最新头，不整版覆盖；只恢复说明字幕或图层时，同样形成局部候选，明确历史字段与版本来路，保留之后的其他修改。用户明确要求完整回到历史版才调用work-version restore。版本冲突先重读当前头和差异，以最新状态重新生成局部候选，不只换expected_version绕过新修改；更新后检查失效证据并绑定准确输出。恢复验证分别检查非空字幕、音轨和人工层，空字段保持不算对应保护证据。

按 [评测](references/evaluation.md) 检查可复现性、前后状态、结果真实性、文字可读与旁白同步，再用 [media-qc](../../atomic/media-qc/SKILL.md) 做技术检查。交付视频、字幕、剪辑表、步骤/证据映射、修改记录和精确版本报告。操作JSON可编辑不等于已验收原生编辑器工程；未听检、未完成真实UI操作复现则保留 DEGRADED。