From 5b555e4313d512cc6b76f9ba9b9553659cf28e61 Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Sun, 7 Jun 2026 14:50:44 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8E=BB=E6=8E=89=E4=BE=9D=E8=B5=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 +++++--- SKILL.md | 3 ++- references/DEVELOPMENT.md | 10 ++++++---- references/REQUIREMENTS.md | 6 ++++-- references/RPA.md | 6 +++++- references/RUNTIME.md | 4 +++- requirements.txt | 10 +--------- tests/README.md | 2 +- tests/test_platform_import.py | 13 ++++++++++++- tests/test_template_runtime_standard.py | 4 ++++ 10 files changed, 43 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 108c940..7c87d5e 100644 --- a/README.md +++ b/README.md @@ -57,13 +57,15 @@ python scripts/main.py version ## Python 依赖（requirements.txt） -- 模板默认声明 `jiangchang-platform-kit>=1.0.11` 作为公共 SDK 依赖；`jiangchang_skill_core` 来自共享 runtime，**不在技能仓库内复制**。 +- `jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等由**宿主共享 runtime** 提供；`jiangchang_skill_core` **不在技能仓库内复制**。 - 新技能**不得 vendored** `scripts/jiangchang_skill_core/`；复制模板后若发现该目录，应删除并改为依赖共享 venv。 -- 在技能**根目录**维护 `requirements.txt`，声明本技能特有的 Python 三方包（在 platform-kit 之外按需追加）。 -- 匠厂宿主在**安装或更新**技能后，会将该文件中的依赖安装到共享 Python runtime： +- 在技能**根目录**维护 `requirements.txt`，**只声明技能特有** Python 三方包；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。 +- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（如 `1.0.11`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。 +- 匠厂宿主在**安装或更新**技能后，会将技能 `requirements.txt` 中的依赖安装到共享 Python runtime： `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`（Windows 示例：`D:\jiangchang-data\python-runtime\.venv`）。 - **Skill 业务代码不得自动 `pip install`**；缺依赖时应在 `health` / preflight 中给出清晰错误。 - **系统级组件**（如 Microsoft Visual C++ Redistributable）**不要**写进 `requirements.txt`；仅在 `health` / preflight 中提示用户自行安装。 +- 独立本地开发环境若缺少公共包，可手动安装；**生产/宿主运行**由共享 runtime 负责，无需在技能内 `pip install playwright`。 ## 公共能力边界 diff --git a/SKILL.md b/SKILL.md index 07f0035..90e53e9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -47,7 +47,8 @@ python {baseDir}/scripts/main.py version - Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 - 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.0.11`（`jiangchang_skill_core` 包）；**新技能不得**在仓库内保留 `scripts/jiangchang_skill_core/` 副本。 - config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。 -- 本技能**特有**的 Python 三方依赖请声明在根目录 `requirements.txt`（默认已含 `jiangchang-platform-kit>=1.0.11`）；宿主安装/更新技能后会自动安装到共享 venv。 +- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。宿主安装/更新技能后会将技能 requirements 安装到共享 venv。 +- `metadata.openclaw.platform_kit_min_version`（当前 `1.0.11`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。 - Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。 - `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。 diff --git a/references/DEVELOPMENT.md b/references/DEVELOPMENT.md index f489d42..043712e 100644 --- a/references/DEVELOPMENT.md +++ b/references/DEVELOPMENT.md @@ -172,10 +172,11 @@ 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`。 +- **公共依赖**（`jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等）由**宿主共享 runtime** 提供，**不要**写入技能 `requirements.txt`。 +- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（如 `1.0.11`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。 +- 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。 - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法： - `pkg>=1.2.0,<2` @@ -183,7 +184,8 @@ scripts/ - 不推荐：`chromadb>=0.5.0` - 推荐：`chromadb>=0.5.23,<0.6` - **不要**把系统组件（VC++ Runtime、浏览器安装包等）写进 `requirements.txt`；这类前置条件写在 `health` / preflight 文档与错误提示中。 -- 若技能无额外 Python 依赖，可保留仅含 `jiangchang-platform-kit>=1.0.11` 的最小 `requirements.txt`。 +- 若技能无额外 Python 依赖，可保留空文件或仅含注释说明；**不要**为 platform-kit 或 playwright 保留占位行。 +- 独立本地开发环境若缺少公共包，可手动安装；**生产/宿主运行**由共享 runtime 负责。 ### 3.3 公共能力不要复制 diff --git a/references/REQUIREMENTS.md b/references/REQUIREMENTS.md index f62a701..cd3af35 100644 --- a/references/REQUIREMENTS.md +++ b/references/REQUIREMENTS.md @@ -166,8 +166,10 @@ ### Python 包依赖（requirements.txt） -- 本技能若需额外 Python 三方包，写入根目录 `requirements.txt`。 -- 匠厂宿主安装/更新技能后，会安装到 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 +- 本技能若需**特有** Python 三方包，写入根目录 `requirements.txt`。 +- `jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。 +- `SKILL.md` 的 `platform_kit_min_version` 是运行契约/兼容性声明，供宿主校验，**不是** pip 依赖声明。 +- 匠厂宿主安装/更新技能后，会将技能 requirements 安装到 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 - 版本须尽量收窄（如 `requests>=2.31.0,<3`），避免共享 venv 冲突。 - **不要**把系统运行时组件（如 Microsoft Visual C++ Redistributable）写进 requirements.txt。 diff --git a/references/RPA.md b/references/RPA.md index a7e33d3..84c4b62 100644 --- a/references/RPA.md +++ b/references/RPA.md @@ -56,8 +56,12 @@ ### 1.2 安装 +生产/宿主运行：`playwright` 由共享 runtime 提供，无需在技能内 `pip install`。 + +独立本地开发环境若缺少 Python 包 `playwright` 时，可手动执行： + ```bash -pip install playwright # 仅装包；用系统 Chrome，无需 playwright install chromium +pip install playwright # 仅独立开发补装；用系统 Chrome，无需 playwright install chromium ``` ### 引用方式 diff --git a/references/RUNTIME.md b/references/RUNTIME.md index 3cff2ac..5dbdbdf 100644 --- a/references/RUNTIME.md +++ b/references/RUNTIME.md @@ -2,7 +2,9 @@ ## 共享 Python Runtime -**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.11` 及其传递依赖）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。 +**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.11` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。 + +技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。 | 场景 | 推荐做法 | |------|----------| diff --git a/requirements.txt b/requirements.txt index b410b02..f012641 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1 @@ -# Skill-specific Python dependencies. -# Keep this file minimal. -# Platform shared APIs are provided by jiangchang-platform-kit from Jiangchang shared runtime. -# -# Required platform SDK. Do not vendor jiangchang_skill_core inside a skill. -jiangchang-platform-kit>=1.0.11 - -# Browser RPA example: uses system Chrome/Edge; no `playwright install chromium` needed. -playwright>=1.42.0,<2 +# 公共依赖由宿主共享 runtime 提供；这里只声明技能特有 Python 依赖。 diff --git a/tests/README.md b/tests/README.md index 5239188..1732c9f 100644 --- a/tests/README.md +++ b/tests/README.md @@ -39,7 +39,7 @@ - [ ] 至少有 1 个缺必填字段 / 非法输入测试。 - [ ] 如果有 adapter，至少覆盖 timeout / unauthorized / invalid response（可用 fake 模拟）。 - [ ] 如果有解析 / 计算 / 校验类业务，至少保留 1 组 golden fixture（脱敏）。 -- [ ] 如果技能有 Python 三方依赖，`requirements.txt` 已声明且版本约束合理（尽量收窄范围）。 +- [ ] 如果技能有**特有** Python 三方依赖，`requirements.txt` 已声明且版本约束合理（尽量收窄范围）；公共依赖（platform-kit、playwright）由宿主共享 runtime 提供，**不要**写入技能 requirements。 - [ ] `health` 能在依赖缺失或原生运行库未就绪时给出清晰、可操作的错误（非裸 traceback）。 - [ ] 真实 API / 真实 RPA 测试只放 `tests/integration/`，并且默认 `.sample`，不默认运行。 diff --git a/tests/test_platform_import.py b/tests/test_platform_import.py index 939a023..eb008bc 100644 --- a/tests/test_platform_import.py +++ b/tests/test_platform_import.py @@ -24,6 +24,14 @@ def _parse_platform_kit_min_version(skill_md_text: str) -> str: return m.group(1).strip() +def _requirement_dependency_lines(req_text: str) -> list[str]: + return [ + line.strip() + for line in req_text.splitlines() + if line.strip() and not line.strip().startswith("#") + ] + + class TestPlatformImportSource(unittest.TestCase): def test_jiangchang_skill_core_not_from_skill_scripts(self) -> None: scripts_dir = os.path.abspath(get_scripts_dir()) @@ -89,7 +97,10 @@ class TestPlatformImportSource(unittest.TestCase): req_path = os.path.join(get_skill_root(), "requirements.txt") with open(req_path, encoding="utf-8") as f: req = f.read() - self.assertIn("jiangchang-platform-kit>=1.0.11", req) + dep_lines = _requirement_dependency_lines(req) + dep_body = "\n".join(dep_lines).lower() + self.assertNotIn("jiangchang-platform-kit", dep_body) + self.assertNotIn("playwright", dep_body) installed = metadata.version("jiangchang-platform-kit") self.assertTrue( diff --git a/tests/test_template_runtime_standard.py b/tests/test_template_runtime_standard.py index e063e72..e258868 100644 --- a/tests/test_template_runtime_standard.py +++ b/tests/test_template_runtime_standard.py @@ -24,6 +24,10 @@ FORBIDDEN_PHRASES = ( "模板通过 vendor 拷贝引用", "vendor 自 platform-kit", "模板 vendor 拷贝在 scripts/jiangchang_skill_core", + "模板默认声明 `jiangchang-platform-kit", + "模板默认包含 `jiangchang-platform-kit", + "默认已含 `jiangchang-platform-kit", + "保留仅含 `jiangchang-platform-kit", ) POSITIVE_MARKERS = (