# 匠厂 技能开发模板（通用业务）

这是一个**规范化的新技能模板仓库**，用于复制出新的 skill 项目；它本身**不是业务 skill**。

## 模板目标

- 对齐当前规范 skill 的目录结构：`assets/`、`references/`、`scripts/`、`tests/`、`evals/`
- 对齐当前规范脚手架分层：`scripts/cli`、`scripts/db`、`scripts/service`、`scripts/util`；公共能力从共享 runtime 的 `jiangchang-platform-kit` 引用
- 提供最小可运行入口：`python scripts/main.py health` / `config-path` / `version`，以及通用任务命令骨架 `run` / `logs` / `log-get`
- 内置 **配置 bootstrap**：`.env.example` 首次落盘到 `{DATA_ROOT}/{USER_ID}/{slug}/.env`，升级后合并缺失 key（见 `scripts/util/config_bootstrap.py`）
- 内置 **隔离测试体系**：`IsolatedDataRoot`、双键环境、`OPENCLAW_TEST_TARGET` 档位与 adapter profile 策略（详见 [`references/TESTING.md`](references/TESTING.md)）
- 让新技能从一开始就按规范落地，不再沿用旧模板的 `docs/`、`optional/`、`skill_main.py` 结构

## 新技能使用步骤

1. 复制本目录为新的 skill 仓库。
2. 全局替换 `your-skill-slug`、`your-platform-key`、`您的技能显示名称` 等占位内容。
3. 修改 `SKILL.md`、`references/` 和 `scripts/util/constants.py`。
4. 在 `scripts/service/task_service.py` 中实现真实业务编排与外部系统对接。
5. 运行 `python tests/run_tests.py -v`，再执行 `python scripts/main.py health`、`version` 做最小验证。

如果你的技能在平台里默认是非公开的（`access_scope = 0`），建议在 `SKILL.md` 的 `metadata.openclaw.developer_ids` 中填写开发者用户 ID 列表。这样在正式发布后，平台会为这些开发者补可见权限，避免「技能已上架但开发者自己在市场中看不到」。

开发教程入口：

- <a href="references/REQUIREMENTS.md" target="_blank" rel="noopener noreferrer">需求文档模板</a>：给技术人员编写和查看研发需求的标准模板
- <a href="references/DEVELOPMENT.md" target="_blank" rel="noopener noreferrer">开发教程</a>：给技术人员的完整开发步骤说明
- <a href="references/TESTING.md" target="_blank" rel="noopener noreferrer">测试开发指南</a>：默认套件、隔离数据根、档位开关与 FakeAdapter 怎么用

## 目录说明

| 路径 | 用途 |
|------|------|
| `SKILL.md` | 技能清单与触发说明模板 |
| `assets/` | 示例输出与轻量 schema |
| `references/` | 面向用户与编排的文档模板 |
| `scripts/` | 规范分层后的代码骨架 |
| `tests/` | 单元测试与分层测试范式（默认根目录 unittest） |
| `evals/` | 人工/半自动评估材料 |
| `requirements.txt` | 本技能 Python 三方依赖声明（由匠厂宿主安装到共享 runtime） |
| `.github/workflows/release_skill.yaml` | 标准发布工作流 |
| `release.ps1` | 对齐现有 skill 的发布脚本入口 |

## 最小命令

```bash
python scripts/main.py health
python scripts/main.py version
```

## 注意

- 不要再往模板里引入旧式 `docs/` 或 `optional/` 目录。
- 新技能若不需要某些目录，也建议先保留结构，再按实际业务填充内容。
- `metadata.openclaw.developer_ids` 是发布元数据，不是用户展示文案；用于非公开技能的开发者默认可见授权。
- **发起 `release.ps1` 之前**，务必确认 `python tests/run_tests.py -v` 已全部通过。

## Python 依赖（requirements.txt）

- `jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等由**宿主共享 runtime** 提供；`jiangchang_skill_core` **不在技能仓库内复制**。
- 新技能**不得 vendored** `scripts/jiangchang_skill_core/`；复制模板后若发现该目录，应删除并改为依赖共享 venv。
- 在技能**根目录**维护 `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`。

## 公共能力边界

以下能力均由 `jiangchang-platform-kit`（共享 runtime 的 `jiangchang_skill_core`）提供，技能只写业务逻辑与薄封装，**不要**在技能内复制实现：

- `config` — `.env` 三级优先级读取与首次落盘
- `runtime_env` — 数据根、用户 ID、兄弟技能根解析
- `unified_logging` — 统一日志与 trace
- `rpa` — 浏览器/桌面/手机 RPA 共享库
- `media_assets` — 共享媒体资源探测与路径解析
- `video_session` — RPA 录屏成片（ffmpeg、字幕、背景音乐）
- `runtime_diagnostics` — `health` 统一 runtime 诊断