重新调整模板

2026-06-07 11:28:45 +08:00
parent ae5466854f
commit 1bbcc65cf3
31 changed files with 448 additions and 1525 deletions
--- a/references/CLI.md
+++ b/references/CLI.md
@@ -9,6 +9,20 @@ python {baseDir}/scripts/main.py health
 python {baseDir}/scripts/main.py version
 ```

+## health 标准输出（runtime diagnostics）
+
+`health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，输出统一 runtime 诊断。典型字段：
+
+- `python_executable` — 当前 Python 解释器路径
+- `platform_kit_version` / `platform_kit_min_version` — 已安装与要求的 platform-kit 版本
+- `jiangchang_skill_core_file` — 公共库加载来源（若来自技能目录副本会报 warning）
+- `media_assets_root` — 共享媒体资源根目录
+- `ffmpeg_path` / `ffmpeg_available` — ffmpeg 探测结果
+- `background_music_mp3_count` — 可用背景音乐数量
+- `runtime_issue[warning|error]` — 非致命/致命问题列表
+
+`health` **只读诊断**，不下载、不修复 media-assets，不执行业务 DB / 邮箱 / 订单等检查。
+
 ## 通用业务命令骨架

 模板默认提供以下命令（复制后按需保留或扩展）：
--- a/references/CONFIG.md
+++ b/references/CONFIG.md
@@ -69,7 +69,7 @@ config.ensure_env_file()                   # 首次把 .env.example copy 到数

 ### 引用方式

-实现位于 `jiangchang-platform-kit` 的 `jiangchang_skill_core.config`；模板 vendor 拷贝在 `scripts/jiangchang_skill_core/config.py`：
+`jiangchang_skill_core.config` 来自共享 runtime 安装的 `jiangchang-platform-kit`；业务代码统一 `from jiangchang_skill_core import config`，**不要在技能内复制 config.py**：

 ```python
 from jiangchang_skill_core import config
--- a/references/DEVELOPMENT.md
+++ b/references/DEVELOPMENT.md
@@ -97,7 +97,6 @@ your-skill/
 ├─ scripts/
 │  ├─ cli/
 │  ├─ db/
-│  ├─ jiangchang_skill_core/
 │  ├─ service/
 │  └─ util/
 ├─ tests/
@@ -125,7 +124,6 @@ scripts/
 ├─ main.py
 ├─ cli/
 ├─ db/
-├─ jiangchang_skill_core/
 ├─ service/
 └─ util/
 ```
@@ -151,9 +149,7 @@ scripts/
 - `util/`
  作用：常量、日志、路径、时间工具、通用帮助函数

- `jiangchang_skill_core/`
-  作用：运行时环境、统一日志、配置读取、RPA 共享库（vendor 自 platform-kit）
-  一般按现有规范技能复制，不要自己乱改结构
+公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.11` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。

 ## 3.2 开发 RPA 类 skill

@@ -168,7 +164,7 @@ scripts/
   from jiangchang_skill_core import config
   from jiangchang_skill_core.rpa import launch_persistent_browser, anti_detect, wait_for_captcha_pass
   ```
-   vendor 源码在 `scripts/jiangchang_skill_core/rpa/`（与 `jiangchang-platform-kit` 保持同步拷贝）。
+   上述 import 来自宿主共享 runtime 安装的 `jiangchang-platform-kit`，不是技能目录副本。
 4. **mock 档必须离线可跑**（`OPENCLAW_TEST_TARGET=mock`）；sim_rpa / real_* 按需单独测。
 5. **桌面/手机**：本期标准见 RPA.md 第 2/3 节，复用 `jiangchang_desktop_sdk` / `screencast`，**不要在新 skill 里重复造包**（尚待实战验证）。

@@ -176,8 +172,9 @@ scripts/

 ### 3.1 `requirements.txt` 依赖规范

-技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能特有的 Python 三方依赖。
+技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能 Python 三方依赖。

+- 模板默认包含 `jiangchang-platform-kit>=1.0.11`（公共 SDK）；复制后保留该行，再按需追加技能特有依赖。
 - 匠厂宿主安装/更新技能后，会将其安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
 - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
@@ -186,7 +183,23 @@ scripts/
  - 不推荐：`chromadb>=0.5.0`
  - 推荐：`chromadb>=0.5.23,<0.6`
 - **不要**把系统组件（VC++ Runtime、浏览器安装包等）写进 `requirements.txt`；这类前置条件写在 `health` / preflight 文档与错误提示中。
- 若技能无额外 Python 依赖，可保留仅含注释的 `requirements.txt`（宿主会识别为 empty 并跳过安装）。
+- 若技能无额外 Python 依赖，可保留仅含 `jiangchang-platform-kit>=1.0.11` 的最小 `requirements.txt`。
+
+### 3.3 公共能力不要复制
+
+以下模块由 platform-kit 提供，技能内**不要**重复实现或 vendored 拷贝：
+
+| 能力 | 导入方式 |
+|------|----------|
+| config | `from jiangchang_skill_core import config` |
+| logging | `from jiangchang_skill_core.unified_logging import ...` 或 `util.logging_config` 薄封装 |
+| runtime_env | `from jiangchang_skill_core.runtime_env import ...` 或 `util.runtime_paths` 薄封装 |
+| rpa | `from jiangchang_skill_core.rpa import ...` |
+| media_assets | `from jiangchang_skill_core.media_assets import ...` |
+| video_session | `from jiangchang_skill_core.rpa.video_session import RpaVideoSession` |
+| runtime_diagnostics | `from jiangchang_skill_core import collect_runtime_diagnostics, format_runtime_health_lines` |
+
+`health` 应委托 `collect_runtime_diagnostics`，不要在 `scripts/util/` 自建 `runtime_diagnostics.py`。

 ## 4. 开发一个新 skill 的标准步骤

--- a/references/RPA.md
+++ b/references/RPA.md
@@ -62,10 +62,9 @@ pip install playwright   # 仅装包；用系统 Chrome，无需 playwright inst

 ### 引用方式

-共享实现位于 `jiangchang-platform-kit` 的 `jiangchang_skill_core.rpa`；模板通过 vendor 拷贝引用：
+共享实现位于宿主共享 runtime 安装的 `jiangchang-platform-kit`（`jiangchang_skill_core.rpa`）。复制后的业务技能直接 import，**技能仓库不得保留 rpa 公共代码副本**：

 ```python
-# scripts/jiangchang_skill_core/rpa/ — vendored from platform-kit
 from jiangchang_skill_core.rpa import (
    launch_persistent_browser,
    anti_detect,
@@ -76,6 +75,9 @@ from jiangchang_skill_core.rpa import (
 from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
 ```

+- `RpaVideoSession` 来自 platform-kit；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析。
+- `health` 对上述资源做只读诊断，不下载、不修复。
+
 完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。

 ---
--- a/references/RUNTIME.md
+++ b/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` 会在测试期间同时设置：
--- a/references/TESTING.md
+++ b/references/TESTING.md
@@ -22,7 +22,8 @@

 必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖：

- CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health` / `version` / `logs` / `log-get` 冒烟；
+- CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟；
+- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.11` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
 - **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移；
 - 运行时：`runtime_paths` 与 **`CLAW_*` / `JIANGCHANG_*` 并发兜底；
 - `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)；