# 运行时约定

## 共享 Python Runtime

**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.13` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。

技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。

| 场景 | 推荐做法 |
|------|----------|
| 日常运行 | 由宿主匠厂触发技能 |
| 手工排查 / 测试机 | 使用共享 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.13+）

`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 下载或修复。并补充 `env_path` / `env_exists` / `example_path` 配置路径字段。

## 配置 bootstrap

- 仓库内 `.env.example` 是配置模板（单一事实来源）。
- 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。
- `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。
- 配置优先级：**进程环境变量** > **用户 `.env`** > **`.env.example` 默认值**。
- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.13`，**不得** vendored `scripts/jiangchang_skill_core/`。

## media-assets / ffmpeg / 背景音乐

背景音乐、ffmpeg 等共享资源由 platform-kit 统一解析，默认路径：

```text
{JIANGCHANG_DATA_ROOT}/shared/media-assets
```

（与 `CLAW_DATA_ROOT` 解析规则一致，由宿主注入。）

RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均由 platform-kit 提供；技能只 import，不重复实现。

## 目录结构

新技能建议采用以下根目录结构：

- `assets/`
- `references/`
- `scripts/`
- `tests/`
- `evals/`

**标准 `scripts/` 分层（不含 `jiangchang_skill_core/` 副本）：**

- `scripts/main.py`：唯一 CLI 入口
- `scripts/cli/`：参数解析与命令分发
- `scripts/db/`：SQLite 或本地持久化层
- `scripts/service/`：业务用例与外部交互
- `scripts/util/`：通用工具、常量、日志、路径薄封装

## 数据路径

推荐：

```text
{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
```

数据库文件建议：

```text
{...}/{skill_slug}.db
```

## 明确禁止

- **不得** vendored `scripts/jiangchang_skill_core/`
- **不得**在技能内本地重复实现 `RuntimeDiagnostics` / `collect_runtime_diagnostics`
- **不得**写死开发机绝对路径作为运行时约定

## 测试时的运行时隔离

本模板的 `tests/_support.IsolatedDataRoot` 会在测试期间同时设置：

- `CLAW_DATA_ROOT` / `JIANGCHANG_DATA_ROOT` → 临时 tempfile 目录
- `CLAW_USER_ID` / `JIANGCHANG_USER_ID` → `_test`

退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。

详见 `references/TESTING.md` 第 3 节。

## 编码与输出

- Windows 终端建议在 `scripts/main.py` 里做 UTF-8 stdout/stderr 包装
- 机读输出优先单行 JSON
- 错误前缀建议统一 `ERROR:`