docs: standardize skill requirements declaration

README.md

@@ -36,6 +36,7 @@
 | `scripts/` | 规范分层后的代码骨架 |
 | `tests/` | 单元测试与分层测试范式（默认根目录 unittest） |
 | `evals/` | 人工/半自动评估材料 |
+| `requirements.txt` | 本技能 Python 三方依赖声明（由匠厂宿主安装到共享 runtime） |
 | `.github/workflows/release_skill.yaml` | 标准发布工作流 |
 | `release.ps1` | 对齐现有 skill 的发布脚本入口 |
 
@@ -52,3 +53,12 @@ python scripts/main.py version
 - 新技能若不需要某些目录，也建议先保留结构，再按实际业务填充内容。
 - `metadata.openclaw.developer_ids` 是发布元数据，不是用户展示文案；用于非公开技能的开发者默认可见授权。
 - **发起 `release.ps1` 之前**，务必确认 `python tests/run_tests.py -v` 已全部通过。
+
+## Python 依赖（requirements.txt）
+
+- 在技能**根目录**维护 `requirements.txt`，声明本技能特有的 Python 三方包。
+- 匠厂宿主在**安装或更新**技能后，会将该文件中的依赖安装到共享 Python runtime：
+  `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`（Windows 示例：`D:\jiangchang-data\python-runtime\.venv`）。
+- 平台通用依赖由宿主 `resources/jiangchang-python-runtime/pyproject.toml` 维护；**不要**把业务依赖写进宿主 pyproject。
+- **Skill 业务代码不得自动 `pip install`**；缺依赖时应在 `health` / preflight 中给出清晰错误。
+- **系统级组件**（如 Microsoft Visual C++ Redistributable）**不要**写进 `requirements.txt`；仅在 `health` / preflight 中提示用户自行安装。

SKILL.md

@@ -38,6 +38,12 @@ python {baseDir}/scripts/main.py health
 python {baseDir}/scripts/main.py version
 ```
 
+## 运行依赖
+
+- Python 运行环境由匠厂宿主注入共享 runtime：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
+- 本技能**特有**的 Python 三方依赖请声明在根目录 `requirements.txt`；宿主安装/更新技能后会自动安装到共享 venv。
+- Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。
+
 ## 重要说明
 
 - 复制后请同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。

references/DEVELOPMENT.md

@@ -103,6 +103,7 @@ your-skill/
 ├─ tests/
 ├─ .gitignore
 ├─ README.md
+├─ requirements.txt
 ├─ release.ps1
 └─ SKILL.md
 ```
@@ -154,6 +155,20 @@ scripts/
   作用：运行时环境与统一日志副本
   一般按现有规范技能复制，不要自己乱改结构
 
+### 3.1 `requirements.txt` 依赖规范
+
+技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能特有的 Python 三方依赖。
+
+- 匠厂宿主安装/更新技能后，会将其安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
+- **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
+- **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
+  - `pkg>=1.2.0,<2`
+- 对**原生扩展 / 高风险依赖**（如 `chromadb`、`onnxruntime`）建议 pin 或窄范围，避免无上限：
+  - 不推荐：`chromadb>=0.5.0`
+  - 推荐：`chromadb>=0.5.23,<0.6`
+- **不要**把系统组件（VC++ Runtime、浏览器安装包等）写进 `requirements.txt`；这类前置条件写在 `health` / preflight 文档与错误提示中。
+- 若技能无额外 Python 依赖，可保留仅含注释的 `requirements.txt`（宿主会识别为 empty 并跳过安装）。
+
 ## 4. 开发一个新 skill 的标准步骤
 
 下面这套顺序建议严格按步骤做，不要一上来就直接写 `service`。

references/REQUIREMENTS.md

@@ -164,6 +164,18 @@
 - `【平台名】`：作用是 `【用途】`
 - `【浏览器 / API / 第三方服务】`：作用是 `【用途】`
 
+### Python 包依赖（requirements.txt）
+
+- 本技能若需额外 Python 三方包，写入根目录 `requirements.txt`。
+- 匠厂宿主安装/更新技能后，会安装到 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
+- 版本须尽量收窄（如 `requests>=2.31.0,<3`），避免共享 venv 冲突。
+- **不要**把系统运行时组件（如 Microsoft Visual C++ Redistributable）写进 requirements.txt。
+
+### 系统运行时前置条件（preflight / health）
+
+- 若依赖 Windows 原生 DLL、本机浏览器 channel 等**系统级**能力，在 `health` / preflight 中检测并提示用户自行安装。
+- 此类依赖**不**通过 pip / requirements.txt 由宿主自动安装。
+
 示例：
 
 ### 兄弟技能依赖

requirements.txt

@@ -0,0 +1,8 @@
+# Skill-specific Python dependencies.
+# Keep this file minimal.
+# Platform-provided shared dependencies are installed by Jiangchang runtime.
+# Add only dependencies required by this skill.
+#
+# Examples:
+# requests>=2.31.0,<3
+# python-dotenv>=1.0.0,<2

tests/README.md

@@ -39,6 +39,8 @@
 - [ ] 至少有 1 个缺必填字段 / 非法输入测试。
 - [ ] 如果有 adapter，至少覆盖 timeout / unauthorized / invalid response（可用 fake 模拟）。
 - [ ] 如果有解析 / 计算 / 校验类业务，至少保留 1 组 golden fixture（脱敏）。
+- [ ] 如果技能有 Python 三方依赖，`requirements.txt` 已声明且版本约束合理（尽量收窄范围）。
+- [ ] `health` 能在依赖缺失或原生运行库未就绪时给出清晰、可操作的错误（非裸 traceback）。
 - [ ] 真实 API / 真实 RPA 测试只放 `tests/integration/`，并且默认 `.sample`，不默认运行。
 
 ---