feat(v1): add secure configuration baseline

.gitignore

@@ -0,0 +1,17 @@
+# Local configuration and credentials
+v1/config.local.json
+*.local.json
+.env
+.env.*
+
+# Runtime artifacts and private evaluation materials
+artifacts/
+testdata/private/
+testdata/videos/
+*.onnx
+*.pt
+
+# Python tooling
+.pytest_cache/
+__pycache__/
+*.py[cod]

docs/03-tech-stack.md

@@ -42,7 +42,8 @@
 | 基线检查 | `./init.ps1` |
 | 旧代码编译检查 | `python -m compileall -q demo` |
 | 旧 GUI 启动 | `Set-Location demo; python main.py` |
-| V1 测试 | T-101 创建 `v1/requirements.txt` 和测试后写入真实 `pytest` 命令 |
+| V1 依赖安装 | `python -m pip install -r v1/requirements.txt`（显式执行；`init.ps1` 不自动安装） |
+| V1 单元测试 | `python -m pytest v1/tests -v` |
 | V2 测试 | T-302 创建 Go 模块后使用 `go test ./...` |
 
 ## 演进决策

docs/06-tasks.md

@@ -14,7 +14,7 @@
 
 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
-| T-101 | 创建 V1 包、依赖清单、示例配置和忽略规则 | T-000 | `v1/` 可导入；真实 RTSP 凭证被拒绝提交；`pytest` 能运行。 | DOING |
+| T-101 | 创建 V1 包、依赖清单、示例配置和忽略规则 | T-000 | `v1/` 可导入；真实 RTSP 凭证被拒绝提交；`pytest` 能运行。 | DONE |
 | T-102 | 实现可重连的视频源与录像回放适配器 | T-101 | 有效本地录像可按时间戳产帧；无效源进入连接错误状态且不崩溃。 | TODO |
 | T-103 | 实现 Pose 适配器与模型来源校验 | T-102 | 输出 person box、17 点和置信度；错误模型或哈希不符时给出明确错误。 | TODO |
 | T-104 | 实现人员跟踪与姿态质量门控 | T-103 | 连续人员维持 ID；低质量、缺失膝踝或空帧不会产生倒地候选。 | TODO |

docs/07-v1-implementation-plan.md

@@ -36,7 +36,7 @@
 - Modify: `.gitignore`
 - Modify: `init.ps1`, `docs/03-tech-stack.md`, `docs/current-state.md`
 
-- [ ] **Step 1: Write the failing configuration test**
+- [x] **Step 1: Write the failing configuration test**
 
 ```python
 from v1.config import load_config
@@ -55,12 +55,12 @@ def test_load_config_resolves_rtsp_environment_variable(tmp_path, monkeypatch):
     assert load_config(config_file).source_url == "rtsp://example"
 ```
 
-- [ ] **Step 2: Run the test to verify it fails**
+- [x] **Step 2: Run the test to verify it fails**
 
 Run: `python -m pytest v1/tests/test_config.py -v`
 Expected: FAIL because `v1.config` does not exist.
 
-- [ ] **Step 3: Implement the smallest configuration interface**
+- [x] **Step 3: Implement the smallest configuration interface**
 
 ```python
 import json
@@ -114,12 +114,12 @@ def load_config(path: Path) -> AppConfig:
 
 `config.local.json`, `artifacts/`, `testdata/private/`, `*.onnx` and camera credentials must be ignored; `config.example.json` contains only `rtsp_url_env`.
 
-- [ ] **Step 4: Run baseline tests and update the standard command**
+- [x] **Step 4: Run baseline tests and update the standard command**
 
 Run: `python -m pytest v1/tests -v`
-Expected: PASS. Update `init.ps1` so it installs `v1/requirements.txt` and runs this command.
+Expected: PASS. Update `init.ps1` so it checks the required runtime imports and runs this command; keep `v1/requirements.txt` as an explicit installation command rather than mutating the environment during verification.
 
-- [ ] **Step 5: Commit**
+- [x] **Step 5: Commit**
 
 ```powershell
 git add .gitignore init.ps1 v1 docs/03-tech-stack.md docs/current-state.md docs/06-tasks.md progress.md

docs/api.md

@@ -15,7 +15,7 @@
   },
   "model": {
     "path": "models/best.pt",
-    "sha256": "填写受控模型哈希",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
     "confidence_threshold": 0.25
   },
   "event": {
@@ -32,7 +32,7 @@
 ```
 
 - `rtsp_url_env` 必填；应用从同名环境变量读取真实 URL。
-- 数值是待现场录像校准的默认值；每个值必须真正进入事件逻辑。
+- 数值是待现场录像校准的默认值；每个值必须真正进入事件逻辑。示例中的全零 SHA-256 只占位配置形状，T-103 必须以受控模型的真实哈希替换并验证后才能启动推理。
 - 缺少环境变量、模型不存在或哈希不符时，应用显示配置错误，不启动监控。
 
 ## 核心数据

docs/current-state.md

@@ -4,18 +4,18 @@
 
 ## 当前快照
 
-- 日期：2026-07-20
-- 阶段：V1 工程化起步；T-101 进行中。
+- 日期：2026-07-21
+- 阶段：V1 工程化起步；T-101 已验收，等待 T-102。
 - 已验证环境：Windows PowerShell；Python 3.8.10；Ultralytics 8.3.205；PyQt5 可导入。
 - 旧生产基线：`demo/main.py`、`demo/fall_detection_gui.py`、`demo/detect_fall.py`、`demo/best.pt`。
-- V1 代码：`v1/` 目录存在但尚无实现。
+- V1 代码：已建立 `v1/__init__.py`、`v1/config.py`、安全的 `config.example.json`、固定依赖清单和配置单元测试；视频源、Pose、跟踪、证据、状态机和 GUI 尚未实现。
 - V2 代码：`v2/` 目录存在但尚无实现。
 - 非代码设计工件：docs/ui/silver-pose-ui-ux-spec.md、docs/ui/2026-07-20-html-prototype-plan.md、docs/ui/silver-pose-v1-prototype.html 与 docs/ui/silver-pose-v2-prototype.html 已建立。v2 HTML 是符合正式浅色 Windows 规范的当前视觉参考：浅灰蓝底、白色卡片，红色只表示确认摔倒、其弹窗和事件证据；文件名中的 v2 只表示原型设计修订，不能理解为 Go V2 实现已开始。v1 HTML 保留为历史深色对照。两者均使用顶部双 Tab、设置草稿与状态交互，且画面、事件和时间都是模拟数据，不连接真实摄像头、模型或网络，也不改变 Phase 1 任务顺序。
-- 测试：`python -m compileall -q demo` 已通过；T-101 开始前 `v1/tests` 尚不存在，因此 `python -m pytest v1/tests -v` 以目录未找到退出，这是待建立的初始测试基线。
+- 测试：`python -m compileall -q demo` 已通过；`python -m pytest v1/tests -v` 当前有 2 个配置测试并已通过。`init.ps1` 会检查运行时依赖、编译旧基线并运行 V1 测试，但不会安装软件包。
 - 模型：`demo/best.pt` 可加载为 YOLO Pose，类别 `person`，`kpt_shape=[17, 3]`；与 `D:\PythonP\fall_detection\best.pt` 哈希一致。
 - 当前标准启动：`./init.ps1`。
 - 当前标准验证：`python -m compileall -q demo`。
-- 当前 blocker：V1 依赖清单、示例配置、回归录像及事件标签尚未创建；真实海康 RTSP 流尚未接入。
+- 当前 blocker：回归录像及事件标签尚未创建；真实海康 RTSP 流尚未接入。
 
 全局环境的 `pip check` 存在其他项目的包冲突，因此它不是 Silver Pose 的验收命令。`init.ps1` 只检查本项目实际导入的 OpenCV、NumPy、Ultralytics 与 PyQt5，并在命令非零退出时失败。
 
@@ -32,9 +32,9 @@
 
 ## 任务状态
 
-- 已完成：T-000（Harness 文档与旧基线快照）。
-- 正在进行：T-101（创建 V1 包、依赖清单、示例配置和忽略规则）。
-- 下一个可领取：完成 T-101 后为 T-102。
+- 已完成：T-000（Harness 文档与旧基线快照）、T-101（V1 安全配置基线）。
+- 正在进行：无。
+- 下一个可领取：T-102。
 
 ## 当前可运行内容
 

init.ps1

@@ -1,13 +1,14 @@
 #!/usr/bin/env pwsh
 
 # Silver Pose 的 Windows 统一启动与验证入口。
-# 当前阶段验证 demo 基线；T-101 创建 v1 后，应同步更新本文件和 docs/03-tech-stack.md。
+# V1 的 requirements.txt 是显式安装清单；本脚本只检查已安装依赖，避免修改当前环境。
 
 $ErrorActionPreference = "Stop"
 Set-Location -Path $PSScriptRoot
 
 $InstallCmd = 'python -c "import cv2, numpy, ultralytics, PyQt5; print(''required Python packages available'')"'
 $VerifyCmd = "python -m compileall -q demo"
+$V1TestCmd = "python -m pytest v1/tests -v"
 $StartCmd = "Set-Location demo; python main.py"
 
 function Invoke-Checked {
@@ -22,6 +23,7 @@ function Invoke-Checked {
 Write-Host "==> 当前目录: $($PWD.Path)"
 Invoke-Checked -Label "检查 Silver Pose Python 依赖" -Command $InstallCmd
 Invoke-Checked -Label "运行 demo 基线验证" -Command $VerifyCmd
+Invoke-Checked -Label "运行 V1 单元测试" -Command $V1TestCmd
 
 Write-Host "==> 图形界面启动命令"
 Write-Host "    $StartCmd"

progress.md

@@ -80,3 +80,12 @@
 - 阻塞：无。
 - 决策：`init.ps1` 保持无副作用的依赖检查与基线验证，不自动安装包；`requirements.txt` 将作为显式、可复现的安装清单。
 - 下一步：先写配置加载与敏感值拒绝的失败测试，再实现最小配置接口。
+
+## 【2026-07-21】T-101 创建 V1 包、依赖清单、示例配置和忽略规则（完成）
+
+- 状态：DONE
+- 变更：新增 `v1` 包、经验证的 `config.py`、仅含环境变量名的公开配置示例、与当前环境一致的 `requirements.txt` 和两项 pytest 配置测试；新增 `.gitignore`，忽略本地配置、事件工件、私有录像和模型导出物。`init.ps1` 现在运行 V1 测试但不自动安装依赖。
+- 验证：先运行 `python -m pytest v1/tests/test_config.py -v`，确认因缺少 `v1.config` 产生预期导入失败；实现后 `./init.ps1` 和 `python -m pytest v1/tests -v` 均通过（2 passed），`python -m compileall -q v1 demo` 通过。公开配置的地址/凭证扫描无匹配，`git check-ignore` 已确认本地配置、事件工件、`.pt` 与 `.onnx` 工件被忽略。
+- 阻塞：无。
+- 决策：配置只允许 `rtsp_url_env` 指向运行环境变量，拒绝内嵌来源地址；确认窗口限制为 1–3 秒。公开示例使用 64 位全零哈希占位，T-103 必须替换为受控模型真实哈希后才可加载模型。
+- 下一步：T-102，先建立录像回放和错误来源的失败测试。

v1/__init__.py

@@ -0,0 +1,5 @@
+"""Silver Pose Python V1 package.
+
+V1 keeps configuration, video acquisition, pose inference, tracking, evidence,
+and temporal event decisions in separate modules.
+"""

v1/config.example.json

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "id": "lobby-camera-01",
+    "rtsp_url_env": "SILVER_POSE_RTSP_URL"
+  },
+  "model": {
+    "path": "models/best.pt",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "confidence_threshold": 0.25
+  },
+  "event": {
+    "keypoint_confidence_threshold": 0.4,
+    "suspect_window_seconds": 0.5,
+    "confirm_window_seconds": 1.8,
+    "recovery_window_seconds": 2.0,
+    "cooldown_seconds": 10.0
+  },
+  "artifacts": {
+    "event_dir": "../artifacts/events"
+  }
+}

v1/config.py

@@ -0,0 +1,146 @@
+"""Validated, credential-safe configuration loading for Silver Pose V1."""
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+
+class ConfigError(ValueError):
+    """Raised when a configuration file cannot safely start V1."""
+
+
+@dataclass(frozen=True)
+class EventConfig:
+    keypoint_confidence_threshold: float
+    suspect_window_seconds: float
+    confirm_window_seconds: float
+    recovery_window_seconds: float
+    cooldown_seconds: float
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    source_id: str
+    source_url: str
+    model_path: Path
+    model_sha256: str
+    confidence_threshold: float
+    event: EventConfig
+    event_dir: Path
+
+
+_ENVIRONMENT_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_SHA256 = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def _mapping(value: Any, field_name: str) -> Dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError("{0} must be an object".format(field_name))
+    return value
+
+
+def _text(value: Any, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError("{0} must be a non-empty string".format(field_name))
+    return value.strip()
+
+
+def _number(value: Any, field_name: str, minimum: float, maximum: float) -> float:
+    try:
+        result = float(value)
+    except (TypeError, ValueError):
+        raise ConfigError("{0} must be numeric".format(field_name))
+    if not minimum <= result <= maximum:
+        raise ConfigError(
+            "{0} must be between {1} and {2}".format(field_name, minimum, maximum)
+        )
+    return result
+
+
+def _resolve_path(config_path: Path, value: Any, field_name: str) -> Path:
+    raw_path = Path(_text(value, field_name))
+    if raw_path.is_absolute():
+        return raw_path
+    return (config_path.parent / raw_path).resolve()
+
+
+def load_config(path: Path) -> AppConfig:
+    """Load one public/local configuration pair without persisting credentials.
+
+    The config file can name an environment variable but must not embed a source
+    address. The resolved address remains in memory only.
+    """
+
+    config_path = Path(path).resolve()
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ConfigError("cannot read config: {0}".format(exc))
+    except json.JSONDecodeError as exc:
+        raise ConfigError("invalid JSON config: {0}".format(exc))
+
+    root = _mapping(raw, "config")
+    source = _mapping(root.get("source"), "source")
+    if "url" in source or "rtsp_url" in source:
+        raise ConfigError("source must define rtsp_url_env, not an embedded address")
+    environment_name = _text(source.get("rtsp_url_env"), "source.rtsp_url_env")
+    if not _ENVIRONMENT_NAME.match(environment_name):
+        raise ConfigError("source.rtsp_url_env must be an environment variable name")
+    source_url = os.environ.get(environment_name)
+    if not source_url:
+        raise ConfigError("missing RTSP environment variable: {0}".format(environment_name))
+
+    model = _mapping(root.get("model"), "model")
+    model_sha256 = _text(model.get("sha256"), "model.sha256").lower()
+    if not _SHA256.match(model_sha256):
+        raise ConfigError("model.sha256 must be a 64-character SHA-256 value")
+
+    event_raw = _mapping(root.get("event"), "event")
+    event = EventConfig(
+        keypoint_confidence_threshold=_number(
+            event_raw.get("keypoint_confidence_threshold"),
+            "event.keypoint_confidence_threshold",
+            0.0,
+            1.0,
+        ),
+        suspect_window_seconds=_number(
+            event_raw.get("suspect_window_seconds"),
+            "event.suspect_window_seconds",
+            0.0,
+            30.0,
+        ),
+        confirm_window_seconds=_number(
+            event_raw.get("confirm_window_seconds"),
+            "event.confirm_window_seconds",
+            1.0,
+            3.0,
+        ),
+        recovery_window_seconds=_number(
+            event_raw.get("recovery_window_seconds"),
+            "event.recovery_window_seconds",
+            0.0,
+            300.0,
+        ),
+        cooldown_seconds=_number(
+            event_raw.get("cooldown_seconds"),
+            "event.cooldown_seconds",
+            0.0,
+            3600.0,
+        ),
+    )
+
+    artifacts = _mapping(root.get("artifacts"), "artifacts")
+    return AppConfig(
+        source_id=_text(source.get("id"), "source.id"),
+        source_url=source_url,
+        model_path=_resolve_path(config_path, model.get("path"), "model.path"),
+        model_sha256=model_sha256,
+        confidence_threshold=_number(
+            model.get("confidence_threshold"), "model.confidence_threshold", 0.0, 1.0
+        ),
+        event=event,
+        event_dir=_resolve_path(config_path, artifacts.get("event_dir"), "artifacts.event_dir"),
+    )

v1/requirements.txt

@@ -0,0 +1,5 @@
+numpy==1.24.4
+opencv-python==4.6.0.66
+ultralytics==8.3.205
+PyQt5==5.15.9
+pytest==8.3.5

v1/tests/test_config.py

@@ -0,0 +1,56 @@
+import json
+
+import pytest
+
+from v1.config import ConfigError, load_config
+
+
+def _write_config(path, source):
+    path.write_text(
+        json.dumps(
+            {
+                "source": source,
+                "model": {
+                    "path": "models/best.pt",
+                    "sha256": "a" * 64,
+                    "confidence_threshold": 0.25,
+                },
+                "event": {
+                    "keypoint_confidence_threshold": 0.4,
+                    "suspect_window_seconds": 0.5,
+                    "confirm_window_seconds": 1.8,
+                    "recovery_window_seconds": 2.0,
+                    "cooldown_seconds": 10.0,
+                },
+                "artifacts": {"event_dir": "artifacts/events"},
+            },
+            ensure_ascii=False,
+        ),
+        encoding="utf-8",
+    )
+
+
+def test_load_config_resolves_source_from_environment_variable(tmp_path, monkeypatch):
+    config_file = tmp_path / "config.json"
+    _write_config(
+        config_file,
+        {"id": "lobby-camera-01", "rtsp_url_env": "SILVER_POSE_RTSP_URL"},
+    )
+    monkeypatch.setenv("SILVER_POSE_RTSP_URL", "rtsp://demo.invalid/live")
+
+    config = load_config(config_file)
+
+    assert config.source_id == "lobby-camera-01"
+    assert config.source_url == "rtsp://demo.invalid/live"
+    assert config.event.confirm_window_seconds == 1.8
+
+
+def test_load_config_rejects_embedded_source_address(tmp_path):
+    config_file = tmp_path / "config.json"
+    _write_config(
+        config_file,
+        {"id": "lobby-camera-01", "url": "rtsp://demo.invalid/live"},
+    )
+
+    with pytest.raises(ConfigError, match="rtsp_url_env"):
+        load_config(config_file)