重新调整模板

references/RUNTIME.md

@@ -1,5 +1,51 @@
 # 运行时约定
 
+## 共享 Python Runtime
+
+**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.11` 及其传递依赖）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
+
+| 场景 | 推荐做法 |
+|------|----------|
+| 日常运行 | 由宿主匠厂触发技能 |
+| 手工排查 / 测试机 | 使用共享 runtime 的 `python.exe` 执行 `scripts/main.py` |
+| **不推荐** | 在技能目录内 `uv run python …` — 可能创建临时 venv，加载不到宿主共享 runtime |
+
+占位命令（路径因环境而异，勿写死本机目录）：
+
+```text
+Windows:
+  {JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health
+
+通用:
+  <shared-python> {baseDir}/scripts/main.py health
+```
+
+`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `CLAW_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
+
+## Runtime 诊断（platform-kit 1.0.11+）
+
+`health` 命令通过 **`jiangchang_skill_core.collect_runtime_diagnostics`** 输出共享 runtime 诊断，**不在技能内重复实现**。典型字段：
+
+- `skill_slug`、`python_executable`、`platform_kit_version`、`platform_kit_min_version`
+- `jiangchang_skill_core_file` — 若从技能目录加载会输出 `runtime_issue[warning]`
+- `CLAW_DATA_ROOT` / `JIANGCHANG_DATA_ROOT` / `resolved_data_root`
+- `media_assets_root`、`ffmpeg_path`、`background_music_*`
+- `record_video_enabled`、`runtime_issue[warning|error]`
+
+`health` 是**只读诊断**，**不会**触发 media-assets 下载或修复。
+
+## media-assets / ffmpeg / 背景音乐
+
+背景音乐、ffmpeg 等共享资源由 platform-kit 统一解析，默认路径：
+
+```text
+{JIANGCHANG_DATA_ROOT}/shared/media-assets
+```
+
+（与 `CLAW_DATA_ROOT` 解析规则一致，由宿主注入。）
+
+RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均由 platform-kit 提供；技能只 import，不重复实现。
+
 ## 目录结构
 
 新技能建议采用以下根目录结构：
@@ -10,14 +56,13 @@
 - `tests/`
 - `evals/`
 
-## `scripts/` 分层
+**标准 `scripts/` 分层（不含 `jiangchang_skill_core/` 副本）：**
 
 - `scripts/main.py`：唯一 CLI 入口
 - `scripts/cli/`：参数解析与命令分发
 - `scripts/db/`：SQLite 或本地持久化层
 - `scripts/service/`：业务用例与外部交互
-- `scripts/util/`：通用工具、常量、日志、路径
-- `scripts/jiangchang_skill_core/`：运行时与统一日志副本
+- `scripts/util/`：通用工具、常量、日志、路径薄封装
 
 ## 数据路径
 
@@ -33,6 +78,12 @@
 {...}/{skill_slug}.db
 ```
 
+## 明确禁止
+
+- **不得** vendored `scripts/jiangchang_skill_core/`
+- **不得**在技能内本地重复实现 `RuntimeDiagnostics` / `collect_runtime_diagnostics`
+- **不得**写死开发机绝对路径作为运行时约定
+
 ## 测试时的运行时隔离
 
 本模板的 `tests/_support.IsolatedDataRoot` 会在测试期间同时设置：