Feature Demo

代码写得快之后，开发者常说不清系统多了什么、怎么用。本 skill 从计划和实际改动找出新增功能，在运行中的系统上走通，录成短视频，再灌进统一模板，生成一份报告。读者是开发者：可以用技术名词，节奏紧凑。

INTENT:
  GOAL: show_developers_what_was_added_and_how_to_use_it
  SUCCESS: [every_user_visible_addition_is_recorded_or_listed_with_reason,
            each_video_replays_a_script_that_asserted_real_results,
            report_states_how_to_use_and_limits_in_the_shared_template]
  NON_GOALS: [acceptance, regression_tests, product_fixes_unless_requested,
              voiceover, native_or_cli_recording]

RULE @boundary:
  MUST: ["输出位置按 用户指定 → 项目已有演示目录 → docs/demos/；每批放在 <演示目录>/<批次>/，批次用计划代号（计划文件名去掉日期），没有计划时用 <日期>-<短 SHA>",
         "把 scripts/record-demo.mjs 和 scripts/render-report.mjs 复制到演示目录，生成物不依赖本 skill；同批演示共用的登录和定位器放 <批次>/shared.mjs",
         "已有同名演示时原位更新脚本并重录，保留人工内容"]
  MUST_NOT: ["给目标项目添加依赖或修改产品代码，除非用户要求",
             "把一次录制通过说成验收通过；演示只证明这条路径在这次录制时走得通"]

RULE @find_additions:
  MUST: ["范围按 用户给定的 git 范围 → 计划完成记录里的提交 → 当前分支相对默认分支的改动；都无法判断时询问",
         "计划取 R-* 需求、§9 场景和实施进度作素材；计划内容只是意图，功能是否存在以 git diff 和实际运行为准",
         "对照后分三类：已实现且可见；计划有但没实现或走不通；改动里有但计划没写。后两类也要报告",
         "细小修复合并成一行列在报告，不单独录制"]
  MUST_NOT: "只读计划就写功能清单"

RULE @environment:
  MUST: ["先读项目的启动说明、已有 e2e-* 与登记的账号来源，复用它们的启动和登录方式",
         "录制前确认实例归属、版本与本次基线一致：看实际监听进程的启动命令，比对运行产物与本地构建的哈希、服务启动时间与最后改动时间；跑的是验收 harness 或测试运行时而非正式入口时，在报告写明；不一致就重新构建或报告阻塞，不换一个能跑的旧版本录。拿不到 SHA 级证据时在报告写明依据",
         =>[writes_not_authorized, "看起来只读的操作也可能写。在 setup 里用 page.context().route 中止并打印非 GET 请求，只放行登录、换票等已核实必要的路径；录制输出出现拦截记录就作废这次录制"],
         "凭据只从项目登记的来源经环境变量传入，交付时只写变量名；没有登记的来源时向用户要",
         "只清理本轮启动的服务和创建的数据"]
  MUST_NOT: ["未授权时在共享实例上写数据、花费真实额度、发消息或调用外部写接口；这类步骤缺授权时先问，或只录不产生副作用的部分并在报告写明",
             "为本方代码造替身；只有范围外依赖未就绪时才在外部边界用替身，并在视频字幕和报告写明",
             "让故障注入或调试用的数据入镜；普通测试数据可以用，并在报告写明"]

WORKFLOW @write_demo:
  DO: ["每个功能一个 <slug>.demo.mjs，走一段连续的真实任务，通常不超过 8 步、一分钟内；格式见下",
       "缺授权不能实跑的结果可以用已有数据展示，比如打开历史记录；字幕和报告写明这是历史结果，没有实跑",
       "默认视口下进入了和计划不同的布局分支时，设 viewport 或切到对应形态，别让演示展示错误的分支",
       "应用要异步加载时设 ready，等内容出现后再开录",
       "用真实运行的页面确定定位器，不凭读代码猜；角色和可见名称优先，应用在 iframe 里时用 frameLocator",
       "字幕写这一步做什么和为什么，界面上看得到的不重复；一句话，语言跟随用户",
       "see 和 gone 写这步操作产生的、功能特有的结果；承诺是具体按钮或入口时就断言操作这个入口的结果"]

RULE @recording:
  MUST: ["Playwright 用项目已有的 1.64 及以上版本；没有时用 npm i --prefix <项目外目录> playwright-core 装到项目外，设 PLAYWRIGHT_ROOT 指向它，并告知会下载浏览器",
         "只回放固定脚本，步骤失败就停，不产出视频"]
  MUST_NOT: ["让模型在录制时现场决定操作", "加长等待或放宽断言，只为让失败的步骤通过"]

RULE @failed_step:
  MUST: ["先看 <slug>.failed.png，判断是产品缺陷、脚本漂移还是环境问题",
         "产品缺陷用用户的话和复现步骤报告，功能写入报告的「没有录制」节，不修产品，不绕开这一步",
         "脚本漂移修脚本后重录；环境问题修环境或记为阻塞"]

RULE @review_video:
  # 脚本通过只说明断言成立，看不出字幕挡住结果或画面露出真实数据。
  MUST: ["每步时刻后约 0.3 秒抽一帧，再加每秒一帧快速扫一遍全程，闪现的中间状态只有这样才看得到；亲自看这些帧。有 ffmpeg 用 ffmpeg，没有就逐段播放或说明未检查",
         "检查：结果在画面内且没被字幕挡住（被挡时设 captionAt: 'top'）；停留够看清；没有密钥、真实客户数据、调试文本或故障注入数据；页面不是加载中",
         "问题改脚本后重录"]

RULE @charts:
  # 视频演示一条路径，图说明这条路径在全局的位置。
  MUST: ["已安装 phoenix-diagram 时读它的 skill，为有分支、等待或多页面流转的功能各生成一张图，放进批次目录并写入 chart；整批有共同主线时再加 overviewChart",
         "页面流转用 workflow；功能的核心是状态变化时才用 statechart，它要先写清规则，规则判定结果写进 limits",
         "图从 @find_additions 核对过的实际行为来画，不只照抄计划",
         =>[phoenix_diagram_unavailable, "不生成图，交付时说明，录制和报告照常"]]
  MUST_NOT: ["未经用户同意安装图解引擎", "把图嵌进别的 HTML 文件；每张图保持独立文件"]

RULE @report:
  MUST: ["读 references/report-format.md，按模板写 <批次>/report.json，不手写 HTML",
         "每个功能写清解决什么、入口和操作、限制；不可录的功能进 sections，也写用法，并标明是否实跑过",
         "三类功能的后两类和细小修复进 sections；项目特有的内容也用 sections 表达",
         "运行 render-report.mjs 生成 index.html；报错就改数据，不改生成结果",
         "在浏览器打开 index.html（headless 也可以），确认每个视频有时长且能播放，图正常显示"]

RULE @handoff:
  MUST: ["给出 index.html 和 report.json 的路径，按三类列功能，报告录制基线、环境和数据来源",
         "列出发现的产品问题、未录制项及原因、用到的额度或写入",
         "说明视频未打码且体积较大，是否提交由用户决定；看报告只需要 report.json、index.html、视频和图，.mjs 只用于重录"]
  MUST_NOT: commit_or_publish_without_request

演示文件

export default {
  title: '任务筛选',
  path: '/tasks',                         // 相对 --url，录制从这里开始
  // 可选：应用在 iframe 里时用 frameLocator；这个元素出现后才开录
  ready: page => page.getByRole('heading', { name: '任务' }),
  // 可选：录制前执行，用于登录和准备数据，不进入视频
  setup: async page => {
    await page.goto('/login');
    await page.getByLabel('邮箱').fill(process.env.DEMO_USER);
    await page.getByLabel('密码').fill(process.env.DEMO_PASSWORD);
    await page.getByRole('button', { name: '登录' }).click();
    await page.waitForURL('**/tasks');
  },
  steps: [
    {
      caption: '筛选弹窗列出全部已有任务',
      do: page => page.getByRole('button', { name: '筛选' }).click(),
      see: page => page.getByRole('heading', { name: '筛选任务' }),
    },
    {
      caption: '点完成回到列表',
      do: page => page.getByRole('button', { name: '完成' }).click(),
      gone: page => page.getByRole('heading', { name: '筛选任务' }),
    },
  ],
};

命令

# 应用已运行；在项目根目录执行
node docs/demos/record-demo.mjs docs/demos/<批次>/<slug>.demo.mjs --url http://127.0.0.1:3000
node docs/demos/render-report.mjs docs/demos/<批次>/report.json

录制退出码：0 成功，1 某一步失败或运行出错，2 参数、演示文件或 Playwright 版本不合法。生成报告退出码：0 成功，2 数据不合法。