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

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

## 模板目标

- 对齐当前规范 skill 的目录结构：`assets/`、`references/`、`scripts/`、`tests/`、`evals/`
- 对齐当前规范脚手架分层：`scripts/cli`、`scripts/db`、`scripts/service`、`scripts/util`、`scripts/jiangchang_skill_core`
- 提供最小可运行入口：`python scripts/main.py health` / `version`，以及通用任务命令骨架 `run` / `logs` / `log-get`
- 内置 **隔离测试体系**：`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）

- 在技能**根目录**维护 `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 中提示用户自行安装。