silver_pose/docs/superpowers/plans/2026-07-22-t205-v1-demo-release.md

T-205 V1 Demo Release Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 生成不含客户数据的 V1 演示包，并让现场操作员能按固定脚本完成预检、演示、证据复查和适用边界说明。

Architecture: v1/release.py 负责可测试的发布包构建与校验；它只复制 V1 运行代码、公开示例、依赖、运行手册和经 SHA-256 校验的模型。v1/scripts/build-v1-release.ps1 只是 Windows 命令行入口。运行手册定义现场步骤，不保存或输出 RTSP 凭证。

Tech Stack: CPython 3.8、PowerShell、hashlib、json、shutil、pytest、PyQt5 V1 应用。

---

Task 1: 可测试的发布包构建器

Files:

• Create: v1/release.py

• Create: v1/tests/test_release.py

• Step 1: 写失败测试，定义受控模型和非敏感清单

def test_build_release_copies_locked_model_and_excludes_local_credentials(tmp_path):
    model = tmp_path / "best.pt"
    model.write_bytes(b"locked-model")
    output = tmp_path / "SilverPose-V1"

    manifest = build_release_package(ROOT, model, sha256_file(model), output)

    assert (output / "v1" / "models" / "best.pt").read_bytes() == b"locked-model"
    assert manifest["model_sha256"] == sha256_file(model)
    assert not list(output.rglob("config.local.json"))
    assert not list(output.rglob("events.jsonl"))

• Step 2: 运行测试确认失败

Run: python -m pytest v1/tests/test_release.py -v

Expected: 因 v1.release 或 build_release_package 不存在而失败。

• Step 3: 实现最小构建器

def build_release_package(project_root, model_path, expected_sha256, output_dir):
    _validate_model(model_path, expected_sha256)
    _copy_tree(project_root / "v1", output_dir / "v1", ignored={"config.local.json", "__pycache__"})
    _copy_file(project_root / "README.md", output_dir / "README.md")
    _copy_file(project_root / "docs" / "demo-runbook.md", output_dir / "docs" / "demo-runbook.md")
    _copy_model(model_path, output_dir / "v1" / "models" / "best.pt")
    return _write_manifest(output_dir, expected_sha256)

清单只包含格式版本、生成时间、模型 SHA-256、包内相对文件路径和文件 SHA-256；不得写入 RTSP URL、账号、密码、客户视频路径或事件工件路径。

• Step 4: 运行测试确认通过

Run: python -m pytest v1/tests/test_release.py -v

Expected: PASS。

Task 2: Windows 发布入口和启动命令

Files:

• Create: v1/scripts/build-v1-release.ps1

• Modify: init.ps1

• Modify: README.md

• Step 1: 写失败测试，定义发布清单校验

def test_verify_release_rejects_a_tampered_model(tmp_path):
    output = _build_test_release(tmp_path)
    (output / "v1" / "models" / "best.pt").write_bytes(b"changed")

    with pytest.raises(ReleaseError, match="model SHA-256"):
        verify_release_package(output)

• Step 2: 运行测试确认失败

Run: python -m pytest v1/tests/test_release.py::test_verify_release_rejects_a_tampered_model -v

Expected: verify_release_package 尚未定义而失败。

• Step 3: 实现清单校验和 PowerShell 入口

param(
  [Parameter(Mandatory = $true)][string]$ModelPath,
  [Parameter(Mandatory = $true)][string]$ModelSha256,
  [string]$Output = "dist/SilverPose-V1"
)
python -m v1.release build --model-path $ModelPath --model-sha256 $ModelSha256 --output $Output

verify_release_package 必须重新计算包内模型和清单列出的每个文件 SHA-256。init.ps1 的 GUI 启动提示改为 python -m v1.app，但继续执行旧 demo/ 的只读编译基线。README 列出依赖安装、无凭证配置方式、V1 启动命令和发布脚本命令。

• Step 4: 运行针对性测试

Run: python -m pytest v1/tests/test_release.py -v

Expected: PASS。

Task 3: 客户演示与证据复查手册

Files:

• Create: docs/demo-runbook.md

• Modify: README.md

• Step 1: 写手册静态守卫测试

def test_demo_runbook_covers_preflight_evidence_and_scope():
    text = (ROOT / "docs" / "demo-runbook.md").read_text(encoding="utf-8")
    for heading in ("启动前检查", "现场演示步骤", "证据复查", "适用边界"):
        assert heading in text
    assert "rtsp://" not in text

• Step 2: 运行测试确认失败

Run: python -m pytest v1/tests/test_release.py::test_demo_runbook_covers_preflight_evidence_and_scope -v

Expected: 手册不存在而失败。

• Step 3: 编写手册

手册必须给出：Windows/依赖/模型哈希/本地配置/摄像头连接测试的预检；演示正常活动和安全模拟摔倒的顺序；确认红色姿态、声音、弹窗和截图的观察点；python -m v1.report artifacts/events 的证据复查；断流不报警的观察；固定俯视、全身大部分可见、单路大厅或走廊的范围限制；以及不作医疗级、全场景或 Pose 模型即摔倒分类器的表述。

• Step 4: 运行手册守卫测试

Run: python -m pytest v1/tests/test_release.py -v

Expected: PASS。

Task 4: 构建并复查无敏感工件的演示包

Files:

• Modify: docs/06-tasks.md

• Modify: docs/current-state.md

• Modify: progress.md

• Step 1: 使用锁定模型构建临时发布包

Run: $releaseRoot = Join-Path $env:TEMP "SilverPose-V1-Release"; $modelSha = (Get-FileHash -Algorithm SHA256 demo/best.pt).Hash.ToLower(); pwsh -File v1/scripts/build-v1-release.ps1 -ModelPath demo/best.pt -ModelSha256 $modelSha -Output $releaseRoot

Expected: 输出 release-manifest.json，模型、代码、公开示例和手册存在，且构建目录中无 config.local.json、events.jsonl、artifacts/ 或 RTSP 地址。

• Step 2: 校验发布包

Run: $releaseRoot = Join-Path $env:TEMP "SilverPose-V1-Release"; $modelSha = (Get-FileHash -Algorithm SHA256 demo/best.pt).Hash.ToLower(); pwsh -File v1/scripts/build-v1-release.ps1 -ModelPath demo/best.pt -ModelSha256 $modelSha -Output $releaseRoot; python -m v1.release verify --package $releaseRoot

Expected: release package verified。

• Step 3: 运行全量验证

Run: ./init.ps1, python -m pytest v1/tests -v, python -m compileall -q v1 demo, git diff --check。

Expected: 所有测试通过，编译退出码 0，差异检查无输出。

• Step 4: 更新任务与执行记录并提交

将 T-205 标为 DONE，记录实际构建/校验命令和“不包含客户工件”的结果；提交代码、测试、手册和任务文档。临时发布目录保持在忽略目录内，不提交。

自检

• 覆盖：发布包、模型哈希、篡改检测、Windows 入口、演示步骤、证据复查、适用边界和无敏感工件。
• 任务没有未定义的函数或占位步骤；每项生产行为均先有失败测试。
• 发布包验证不依赖真实 RTSP，也不打印或写入凭证。