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

这是一个规范化的新技能模板仓库，用于复制出新的 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）
• 让新技能从一开始就按规范落地，不再沿用旧模板的 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 列表。这样在正式发布后，平台会为这些开发者补可见权限，避免「技能已上架但开发者自己在市场中看不到」。

开发教程入口：

• 需求文档模板：给技术人员编写和查看研发需求的标准模板
• 开发教程：给技术人员的完整开发步骤说明
• 测试开发指南：默认套件、隔离数据根、档位开关与 FakeAdapter 怎么用

目录说明

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

最小命令

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 中提示用户自行安装。