hubstudio-desktop 0.1.0__tar.gz

hubstudio_desktop-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# K-Q-4.7 D2 (Sprint 4 batch 5 prep, 老大 2026-05-06):
+# build-time copies populated by scripts/prebuild.py — never commit.
+# References:
+#   - architecture v5.1.2 [12.5.B.3] D2 实施清单
+#   - spec sprint-4-release-prep [7.7] / [6.5] 批 5 DoR 第 6 项
+src/hubstudio_sdk/
+src/hubstudio_desktop/_skills_snapshot/
+
+# Build artefacts
+build/
+dist/
+*.egg-info/
+
+# venv used for local D2 verification (not committed)
+.venv/

hubstudio_desktop-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: hubstudio-desktop
+Version: 0.1.0
+Summary: HubStudio Desktop — local automation GUI on top of hubstudio-skills (Sprint 1).
+Project-URL: Homepage, https://github.com/zota957525/hubstudio-skills
+Project-URL: Repository, https://github.com/zota957525/hubstudio-skills
+Author: zota957525
+License: MIT
+Keywords: agent,browser-automation,fingerprint-browser,hubstudio,nicegui,pydantic-ai
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.14,>=3.11
+Requires-Dist: aiohttp<4,>=3.9
+Requires-Dist: cryptography<46,>=42
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: loguru<1,>=0.7
+Requires-Dist: nicegui<4,>=3.0
+Requires-Dist: playwright<2,>=1.45
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pywebview<6,>=5.0; sys_platform == 'win32'
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: aiohttp<4,>=3.9; extra == 'dev'
+Requires-Dist: pre-commit<5,>=3.7; extra == 'dev'
+Requires-Dist: pyright<2,>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
+Requires-Dist: pytest-httpx<1,>=0.30; extra == 'dev'
+Requires-Dist: pytest-mock<4,>=3.12; extra == 'dev'
+Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
+Requires-Dist: pytest-vcr<2,>=1.0.2; extra == 'dev'
+Requires-Dist: pytest-xdist<4,>=3.5; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff<1,>=0.5; extra == 'dev'
+Requires-Dist: vcrpy<8,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hubstudio-desktop
+
+[![CI](https://github.com/zota957525/hubstudio-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/zota957525/hubstudio-skills/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/zota957525/hubstudio-skills/branch/main/graph/badge.svg)](https://codecov.io/gh/zota957525/hubstudio-skills)
+
+> Local Windows GUI on top of `hubstudio-skills`. Drives HubStudio fingerprint browsers
+> through pydantic-ai + NiceGUI native + Playwright `connect_over_cdp`.
+>
+> **Status**: **Sprint 4 release prep — batches 1-4 closed** (2026-05-06). 484+ unit
+> tests + 9 e2e scenarios green, line coverage >=85% repo-wide and >=80% on the
+> `ui/` sub-gate (settings.py 99%, lnk_creator.py 100%, main.py 94%), ruff /
+> pyright clean, real DeepSeek + OpenRouter HTTPS cassettes recorded (K1 v2 —
+> Gemini via OpenRouter routing, Ollama deferred to v0.2), pywebview Windows
+> matrix CI active, first-run 4-step wizard wired, i18n zh-CN / en-US toggle,
+> desktop `.lnk` shortcut on first launch, `--health-check` CLI active. Sprint
+> 4 batch 5 (`uv publish` first PyPI release) remaining.
+
+---
+
+## Install
+
+### Standard install (recommended)
+
+```bash
+uv tool install hubstudio-desktop
+```
+
+That's it. After installation:
+
+- Type `hubstudio-desktop` in any terminal to launch the GUI
+- A "HubStudio Desktop.lnk" shortcut appears on your desktop on first launch
+- Run `hubstudio-desktop --health-check` for non-interactive provider /
+  connection diagnostics (exit code 0 / 1 / 2)
+
+### Alternative: pip install
+
+```bash
+pip install hubstudio-desktop
+hubstudio-desktop  # launches NiceGUI native window
+```
+
+### Developer install (from monorepo)
+
+`hubstudio-sdk` ships as a **vendored wheel** in `desktop/vendor/` (K-Q-3.1
+v0.5 — 2026-05-05) and is automatically copied into the published wheel by
+the K-Q-4.7 D2 prebuild hook (architecture v5.1.2 [12.5.B]). For local
+development:
+
+```bash
+# from repo root
+pip install desktop/vendor/hubstudio_sdk-0.1.0-py3-none-any.whl
+pip install -e desktop[dev]
+playwright install chromium  # for CDP smoke tests; CI installs separately
+```
+
+This pattern avoids hatchling's PEP 508 file-relative-path quirk and works
+identically in CI / dev / fresh checkout. The wheel ships PEP 561 `py.typed`
+marker so pyright treats it as fully typed (K-Q-3.5 audit list trimmed to 4
+libs in Sprint 3 — google-genai removed under K1 v2, hubstudio-sdk vendored).
+
+#### Upgrading hubstudio-sdk
+
+The SDK source lives in a separate user project (monorepo sub-package) and
+stays **local-only** by design — it does **not** publish to PyPI. The
+vendored-wheel pattern makes this self-contained: every consumer reads it
+from `desktop/vendor/`. To roll a new wheel:
+
+```bash
+cd /path/to/hubstudio-sdk-source
+python -m build --wheel --outdir /path/to/hubstudio-skills/desktop/vendor/
+# git rm old wheel + git add new wheel + commit (in hubstudio-skills repo)
+pip install desktop/vendor/hubstudio_sdk-X.Y.Z-py3-none-any.whl
+pip install -e desktop[dev]
+```
+
+Tests use fakes and never import the real SDK at runtime (NOT-Q-5: zero real
+network traffic). The runtime falls back gracefully when the SDK is absent.
+
+---
+
+## First-launch SmartScreen warning
+
+When you first run `hubstudio-desktop`, Windows may show:
+
+> **Windows protected your PC** — Microsoft Defender SmartScreen prevented an
+> unrecognized app from starting. Running this app might put your PC at risk.
+
+**This is expected** — `hubstudio-desktop` is not code-signed (we chose not
+to purchase an EV certificate for v0.1; see [why](docs/troubleshooting.md#why-smartscreen-warning)).
+
+To proceed:
+
+1. Click **More info** (small link below the bold title)
+2. Click **Run anyway** (button that appears after step 1)
+
+After this one-time approval, Windows will remember your choice and not
+prompt again on subsequent launches.
+
+![SmartScreen warning screenshot](docs/img/smartscreen-warning.png)
+
+> Full troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md).
+
+---
+
+## Desktop shortcut
+
+On first launch, hubstudio-desktop creates a `.lnk` shortcut on your desktop
+pointing to itself (Sprint 4 batch 3 / K-Q-4.2 = C self-implemented
+PowerShell COM). You can double-click this shortcut to relaunch instead of
+typing the command.
+
+If shortcut creation fails (e.g. PowerShell unavailable in your environment,
+Defender blocks subprocess, or you don't have desktop write permission),
+this is **non-fatal** — the app launches normally without a shortcut. See
+[troubleshooting](docs/troubleshooting.md#desktop-shortcut-not-created) for
+manual creation steps and how to retry.
+
+---
+
+## Diagnostics: `--health-check`
+
+For non-interactive diagnostics (CI / remote support / "is my config OK?"):
+
+```bash
+hubstudio-desktop --health-check
+```
+
+Output:
+
+```
+DeepSeek:   Healthy   (latency 234ms)
+OpenRouter: Healthy   (latency 412ms)
+HubStudio:  Healthy   (cdp_url=http://localhost:6873 ok)
+KB:         Healthy   (3 skills loaded: hs1, hs2, hs3)
+
+overall_status: healthy
+```
+
+Exit codes:
+
+- `0` — all components healthy
+- `1` — degraded (some provider unreachable but core works)
+- `2` — critical failure (e.g. HubStudio offline, KB missing, or pywebview
+  / WebView2 missing on Windows)
+
+Output language follows your system locale (zh-CN by default per K-Q-4.5 /
+en-US when system locale is English). To force English from a Chinese
+machine: `LANG=en_US.UTF-8 hubstudio-desktop --health-check`. See the i18n
+locale switch section of [troubleshooting](docs/troubleshooting.md#i18n-locale-switch).
+
+---
+
+## Run
+
+```bash
+hubstudio-desktop          # launches NiceGUI native window
+hubstudio-desktop --no-native       # browser tab fallback (dev / WSL)
+hubstudio-desktop --port 9000        # custom port
+hubstudio-desktop --reset-data       # wipe runtime tables (destructive)
+hubstudio-desktop --skip-health-check
+hubstudio-desktop --health-check     # CLI-only diagnostics, see above
+```
+
+## Test
+
+```bash
+cd desktop
+
+ruff check src/ tests/ scripts/
+ruff format --check src/ tests/ scripts/
+pyright src/ tests/ scripts/
+python scripts/check-section-refs.py    # docstring lint gate
+python scripts/check-i18n-coverage.py    # i18n key coverage gate
+
+pytest                                                       # full suite (484+ unit + 9 e2e)
+pytest -m "not slow" --cov=src/hubstudio_desktop --cov-fail-under=85
+pytest --cov=src/hubstudio_desktop/ui --cov-fail-under=80    # ui sub-gate
+pytest tests/e2e/ -v                                         # 3 happy-path + wildcard + matrix scenarios
+```
+
+## Layout
+
+```
+desktop/
+├── src/hubstudio_desktop/   # production code (8 modules + i18n + lnk_creator)
+├── tests/                    # 484+ unit tests + 9 e2e scenarios
+│   ├── core/ storage/ agent/ automation/ knowledge/ ui/
+│   ├── fakes/ fixtures/ helpers/
+│   └── e2e/                  # full-loop / eventbus-wildcard / 3 scenarios /
+│                             # pywebview-matrix / real-providers-recording
+├── scripts/check-section-refs.py
+├── scripts/check-i18n-coverage.py
+├── data/                     # K5 hardened YAML / JSON
+├── docs/                     # release / rollback handbooks, ADRs, troubleshooting
+├── locales/                  # zh-CN / en-US translation tables (114 keys)
+└── pyproject.toml
+```
+
+## CI
+
+`.github/workflows/ci.yml` runs on push to `main`, every PR, and manual
+`workflow_dispatch`. Jobs:
+
+1. **lint** — `ruff check` + `ruff format --check`
+2. **typecheck** — `pyright src/ tests/ scripts/` (strict)
+3. **test** — matrix `os: [ubuntu, windows] x python: [3.11, 3.12]`; coverage
+   gate `--cov-fail-under=85`; uploads to Codecov from the ubuntu-py3.11 cell
+4. **win_lnk_real** — Sprint 4 batch 3 windows-latest matrix exercising real
+   `.lnk` creation via PowerShell COM
+5. **deps** — `pip-audit` (report-only; non-blocking)
+
+## References
+
+- Project constitution: `../CLAUDE.md`
+- Spec: `../specs/hubstudio-desktop-init/spec.md`
+- Architecture: `../specs/hubstudio-desktop-init/architecture.md`
+- Sprint 2 plan: `../specs/sprint-2-foundation/spec.md`
+- Sprint 2 closing report: `../specs/sprint-2-foundation/sprint-closing-report.md`
+- Sprint 4 plan: `../specs/sprint-4-release-prep/spec.md`
+- Sprint 4 release SOP: `../specs/sprint-4-release-prep/release-path-sop.md`
+- Troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)

hubstudio_desktop-0.1.0/README.md

@@ -0,0 +1,222 @@
+# hubstudio-desktop
+
+[![CI](https://github.com/zota957525/hubstudio-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/zota957525/hubstudio-skills/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/zota957525/hubstudio-skills/branch/main/graph/badge.svg)](https://codecov.io/gh/zota957525/hubstudio-skills)
+
+> Local Windows GUI on top of `hubstudio-skills`. Drives HubStudio fingerprint browsers
+> through pydantic-ai + NiceGUI native + Playwright `connect_over_cdp`.
+>
+> **Status**: **Sprint 4 release prep — batches 1-4 closed** (2026-05-06). 484+ unit
+> tests + 9 e2e scenarios green, line coverage >=85% repo-wide and >=80% on the
+> `ui/` sub-gate (settings.py 99%, lnk_creator.py 100%, main.py 94%), ruff /
+> pyright clean, real DeepSeek + OpenRouter HTTPS cassettes recorded (K1 v2 —
+> Gemini via OpenRouter routing, Ollama deferred to v0.2), pywebview Windows
+> matrix CI active, first-run 4-step wizard wired, i18n zh-CN / en-US toggle,
+> desktop `.lnk` shortcut on first launch, `--health-check` CLI active. Sprint
+> 4 batch 5 (`uv publish` first PyPI release) remaining.
+
+---
+
+## Install
+
+### Standard install (recommended)
+
+```bash
+uv tool install hubstudio-desktop
+```
+
+That's it. After installation:
+
+- Type `hubstudio-desktop` in any terminal to launch the GUI
+- A "HubStudio Desktop.lnk" shortcut appears on your desktop on first launch
+- Run `hubstudio-desktop --health-check` for non-interactive provider /
+  connection diagnostics (exit code 0 / 1 / 2)
+
+### Alternative: pip install
+
+```bash
+pip install hubstudio-desktop
+hubstudio-desktop  # launches NiceGUI native window
+```
+
+### Developer install (from monorepo)
+
+`hubstudio-sdk` ships as a **vendored wheel** in `desktop/vendor/` (K-Q-3.1
+v0.5 — 2026-05-05) and is automatically copied into the published wheel by
+the K-Q-4.7 D2 prebuild hook (architecture v5.1.2 [12.5.B]). For local
+development:
+
+```bash
+# from repo root
+pip install desktop/vendor/hubstudio_sdk-0.1.0-py3-none-any.whl
+pip install -e desktop[dev]
+playwright install chromium  # for CDP smoke tests; CI installs separately
+```
+
+This pattern avoids hatchling's PEP 508 file-relative-path quirk and works
+identically in CI / dev / fresh checkout. The wheel ships PEP 561 `py.typed`
+marker so pyright treats it as fully typed (K-Q-3.5 audit list trimmed to 4
+libs in Sprint 3 — google-genai removed under K1 v2, hubstudio-sdk vendored).
+
+#### Upgrading hubstudio-sdk
+
+The SDK source lives in a separate user project (monorepo sub-package) and
+stays **local-only** by design — it does **not** publish to PyPI. The
+vendored-wheel pattern makes this self-contained: every consumer reads it
+from `desktop/vendor/`. To roll a new wheel:
+
+```bash
+cd /path/to/hubstudio-sdk-source
+python -m build --wheel --outdir /path/to/hubstudio-skills/desktop/vendor/
+# git rm old wheel + git add new wheel + commit (in hubstudio-skills repo)
+pip install desktop/vendor/hubstudio_sdk-X.Y.Z-py3-none-any.whl
+pip install -e desktop[dev]
+```
+
+Tests use fakes and never import the real SDK at runtime (NOT-Q-5: zero real
+network traffic). The runtime falls back gracefully when the SDK is absent.
+
+---
+
+## First-launch SmartScreen warning
+
+When you first run `hubstudio-desktop`, Windows may show:
+
+> **Windows protected your PC** — Microsoft Defender SmartScreen prevented an
+> unrecognized app from starting. Running this app might put your PC at risk.
+
+**This is expected** — `hubstudio-desktop` is not code-signed (we chose not
+to purchase an EV certificate for v0.1; see [why](docs/troubleshooting.md#why-smartscreen-warning)).
+
+To proceed:
+
+1. Click **More info** (small link below the bold title)
+2. Click **Run anyway** (button that appears after step 1)
+
+After this one-time approval, Windows will remember your choice and not
+prompt again on subsequent launches.
+
+![SmartScreen warning screenshot](docs/img/smartscreen-warning.png)
+
+> Full troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md).
+
+---
+
+## Desktop shortcut
+
+On first launch, hubstudio-desktop creates a `.lnk` shortcut on your desktop
+pointing to itself (Sprint 4 batch 3 / K-Q-4.2 = C self-implemented
+PowerShell COM). You can double-click this shortcut to relaunch instead of
+typing the command.
+
+If shortcut creation fails (e.g. PowerShell unavailable in your environment,
+Defender blocks subprocess, or you don't have desktop write permission),
+this is **non-fatal** — the app launches normally without a shortcut. See
+[troubleshooting](docs/troubleshooting.md#desktop-shortcut-not-created) for
+manual creation steps and how to retry.
+
+---
+
+## Diagnostics: `--health-check`
+
+For non-interactive diagnostics (CI / remote support / "is my config OK?"):
+
+```bash
+hubstudio-desktop --health-check
+```
+
+Output:
+
+```
+DeepSeek:   Healthy   (latency 234ms)
+OpenRouter: Healthy   (latency 412ms)
+HubStudio:  Healthy   (cdp_url=http://localhost:6873 ok)
+KB:         Healthy   (3 skills loaded: hs1, hs2, hs3)
+
+overall_status: healthy
+```
+
+Exit codes:
+
+- `0` — all components healthy
+- `1` — degraded (some provider unreachable but core works)
+- `2` — critical failure (e.g. HubStudio offline, KB missing, or pywebview
+  / WebView2 missing on Windows)
+
+Output language follows your system locale (zh-CN by default per K-Q-4.5 /
+en-US when system locale is English). To force English from a Chinese
+machine: `LANG=en_US.UTF-8 hubstudio-desktop --health-check`. See the i18n
+locale switch section of [troubleshooting](docs/troubleshooting.md#i18n-locale-switch).
+
+---
+
+## Run
+
+```bash
+hubstudio-desktop          # launches NiceGUI native window
+hubstudio-desktop --no-native       # browser tab fallback (dev / WSL)
+hubstudio-desktop --port 9000        # custom port
+hubstudio-desktop --reset-data       # wipe runtime tables (destructive)
+hubstudio-desktop --skip-health-check
+hubstudio-desktop --health-check     # CLI-only diagnostics, see above
+```
+
+## Test
+
+```bash
+cd desktop
+
+ruff check src/ tests/ scripts/
+ruff format --check src/ tests/ scripts/
+pyright src/ tests/ scripts/
+python scripts/check-section-refs.py    # docstring lint gate
+python scripts/check-i18n-coverage.py    # i18n key coverage gate
+
+pytest                                                       # full suite (484+ unit + 9 e2e)
+pytest -m "not slow" --cov=src/hubstudio_desktop --cov-fail-under=85
+pytest --cov=src/hubstudio_desktop/ui --cov-fail-under=80    # ui sub-gate
+pytest tests/e2e/ -v                                         # 3 happy-path + wildcard + matrix scenarios
+```
+
+## Layout
+
+```
+desktop/
+├── src/hubstudio_desktop/   # production code (8 modules + i18n + lnk_creator)
+├── tests/                    # 484+ unit tests + 9 e2e scenarios
+│   ├── core/ storage/ agent/ automation/ knowledge/ ui/
+│   ├── fakes/ fixtures/ helpers/
+│   └── e2e/                  # full-loop / eventbus-wildcard / 3 scenarios /
+│                             # pywebview-matrix / real-providers-recording
+├── scripts/check-section-refs.py
+├── scripts/check-i18n-coverage.py
+├── data/                     # K5 hardened YAML / JSON
+├── docs/                     # release / rollback handbooks, ADRs, troubleshooting
+├── locales/                  # zh-CN / en-US translation tables (114 keys)
+└── pyproject.toml
+```
+
+## CI
+
+`.github/workflows/ci.yml` runs on push to `main`, every PR, and manual
+`workflow_dispatch`. Jobs:
+
+1. **lint** — `ruff check` + `ruff format --check`
+2. **typecheck** — `pyright src/ tests/ scripts/` (strict)
+3. **test** — matrix `os: [ubuntu, windows] x python: [3.11, 3.12]`; coverage
+   gate `--cov-fail-under=85`; uploads to Codecov from the ubuntu-py3.11 cell
+4. **win_lnk_real** — Sprint 4 batch 3 windows-latest matrix exercising real
+   `.lnk` creation via PowerShell COM
+5. **deps** — `pip-audit` (report-only; non-blocking)
+
+## References
+
+- Project constitution: `../CLAUDE.md`
+- Spec: `../specs/hubstudio-desktop-init/spec.md`
+- Architecture: `../specs/hubstudio-desktop-init/architecture.md`
+- Sprint 2 plan: `../specs/sprint-2-foundation/spec.md`
+- Sprint 2 closing report: `../specs/sprint-2-foundation/sprint-closing-report.md`
+- Sprint 4 plan: `../specs/sprint-4-release-prep/spec.md`
+- Sprint 4 release SOP: `../specs/sprint-4-release-prep/release-path-sop.md`
+- Troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)

hubstudio_desktop-0.1.0/data/README.md

@@ -0,0 +1,110 @@
+# desktop/data/ 目录索引
+
+本目录存放 hubstudio-desktop 运行时加载的静态数据文件（K5 硬化数据层）。
+
+数据来源：从 `skills/hs1`、`hs2`、`hs3` 的 Markdown 文档中提取算法性和平台行为性内容，
+转换为机器可读的 JSON 格式（D1 决策：与 hs2 源 .json 同构、解析快、SQLite json1 兼容）。
+原始 Markdown 文件保留在 `skills/` 目录，同时服务 Claude Code 用户。
+
+## 文件清单
+
+### domains/reddit-com.json
+
+- 用途：Reddit 域名自动化模板库，包含页面元素选择器、经验处理器和任务流程定义
+- 来源：`skills/hs2-domain-template/examples/reddit-com.json`（K5 内容拆分，格式转 yaml）
+- Schema 权威源：`specs/hubstudio-desktop-init/architecture.md [3.6]` / `spec.md [19]`
+- 字段结构：
+  - `_domain` / `_description` / `_version` / `_updated_at`：元信息
+  - `global`：全站通用经验处理器（cookie 弹窗、登录重定向等）
+  - `pages`：按 URL 路径分组的元素选择器和经验处理器
+  - `tasks`：可重放任务流程定义（含参数 schema 和 flow DSL）
+- 加载入口：`automation/domain_models.py`（Sprint 0b，DomainTemplate Pydantic 模型校验）
+
+### safety_presets.json
+
+- 用途：安全门控三档预设（保守 / 中等 / 激进），供运行时选择后注入域名 JSON 的 `safety` 段
+- 来源：`skills/hs3-matrix-ops/references/safety-system.md` 第 5 节"三种预设档位"
+- Schema 权威源：`specs/hubstudio-desktop-init/spec.md [19]` / `architecture.md [5.13]`
+- 字段结构：
+  - `presets.conservative`：保守档（新账号 / 高风险平台）
+  - `presets.moderate`：中等档（已升温账号 / 正常运营）
+  - `presets.aggressive`：激进档（内部测试 / 低风控平台，不建议生产使用）
+  - 每档含 `safety.rate_limits`、`safety.warmup.phases`、`safety.timing`
+- 字段语义：与 `hubstudio-sdk` `agent.py` `DomainState` 读取字段严格对齐
+  - `rate_limits.<action>.daily_max`：每日上限（int，-1 = 无上限）
+  - `rate_limits.<action>.cooldown`：冷却范围 [min_s, max_s]（二元数组）
+  - `warmup.phases[].days`：[start_day, end_day]（含两端，从 first_used_date 起算）
+  - `timing.active_hours`：[start_h, end_h)（本机时区）
+- 加载入口：`automation/safety_engine.py`（Sprint 0b，占位；待架构师 D13 决定具体加载路径）
+
+### known_rules.json
+
+- 用途：平台行为性和算法性规则列表，供 `platform_rules/` 模块在自动化执行时检查和应用
+- 来源：`skills/hs1-hubstudio-sdk/references/known-issues.md`（K5 内容拆分，仅硬化算法性规则）
+- Schema 权威源：`specs/hubstudio-desktop-init/spec.md [19]`
+- 字段结构：
+  - `id`：规则唯一标识符（`snake_case`）
+  - `domain`：适用域名（`"*"` = 全平台）
+  - `scenario`：触发场景描述
+  - `category`：`platform_behavior`（平台行为规则）或 `algorithmic`（算法性规则）
+  - `rule`：一句话规则摘要
+  - `detail`：详细说明
+  - `implementation_hint`：代码级实现提示（伪代码）
+  - `why`：为什么要这样做
+  - `fallback`：规则失败时的降级策略
+  - `platform_rule_file`：实现该规则的目标代码文件路径
+- 加载入口：`automation/platform_rules/{reddit,quora,...}.py`（Sprint 0b）
+- 硬化范围说明：
+  - 已硬化（本文件）：Reddit URL 搜索导航、CDP connect 方式、DOM snapshot 时机、端口动态获取等
+  - 保留 Skills（不硬化）：GBK 编码经验、录制器 Shadow DOM 注意事项、OpenRouter 模型差异、
+    WaitStrategy 序列化限制等经验性陷阱
+
+## Schema 权威源
+
+| 文件 | 权威源 |
+|---|---|
+| `domains/reddit-com.json` | `architecture.md [3.6]`（域名模板 Pydantic 模型）/ `spec [19]`（K5 硬化清单） |
+| `safety_presets.json` | `spec [19]`（K5 硬化清单）/ `architecture.md [5.13]`（D13 数据持久化） |
+| `known_rules.json` | `spec [19]`（K5 硬化清单）/ `automation/platform_rules/` 代码实现 |
+
+## 运行时加载入口（占位，Sprint 0b 实现）
+
+```
+desktop/src/hubstudio_desktop/
+├── automation/
+│   ├── domain_models.py        # 加载 domains/*.json，Pydantic 校验
+│   ├── platform_rules/
+│   │   ├── reddit.py           # 消费 known_rules.json 中 domain=reddit.com 的规则
+│   │   └── ...                 # 其他平台
+│   └── safety_engine.py        # 加载 safety_presets.json，注入 DomainState.safety 段
+（注：上述 desktop/src/hubstudio_desktop/ 是 src layout 路径，
+F2 修复：原 desktop/agent/ 已迁到此处）
+```
+
+## 用户编辑指南
+
+### 调整 safety_presets.json
+
+1. 打开 `desktop/data/safety_presets.json`，找到要调整的档位（conservative / moderate / aggressive）
+2. 修改对应 `rate_limits.<action>.daily_max` 或 `cooldown` 值
+3. `cooldown` 必须是二元数组 `[min_s, max_s]`，不能拆分为两个字段
+4. `active_hours` 必须是二元数组 `[start_h, end_h)`，end 不包含
+5. 保存后重启应用生效（Sprint 0b 实现热重载前需重启）
+6. 注意：硬编码阈值（域名冷却时长、连续失败触发冷却等）在 `hubstudio-sdk` 代码中，
+   无法通过本文件覆盖
+7. JSON 编辑建议用 VS Code（自带 jsonschema 校验 + 语法高亮）
+
+### 新增域名模板
+
+1. 参照 `domains/reddit-com.json` 结构新建 `domains/{domain}.json`
+2. 必填字段：`_domain` / `_description` / `_version` / `_updated_at`
+3. 同时在 `automation/platform_rules/{domain}.py` 中注册对应规则
+4. 同时在 `skills/hs2-domain-template/examples/<domain>.json` 保留 JSON 版本
+   （K5 原则：skills/ 是 Claude Code 用户的知识库，desktop/data/ 是运行时数据）
+
+### 新增 known_rules 规则
+
+1. 在 `known_rules.json` 的 `rules:` 列表末尾追加新规则
+2. 必填字段：`id`（唯一）/ `domain` / `scenario` / `category` / `rule` / `why` / `fallback`
+3. 同时在对应 `platform_rule_file` 代码中实现该规则
+4. 仅硬化算法性 / 平台行为性规则；经验性陷阱仍写入 `known-issues.md`（Skills 保留）