skill-template/references/RUNTIME.md

运行时约定

目录结构

新技能建议采用以下根目录结构：

• assets/
• references/
• scripts/
• tests/
• evals/

scripts/ 分层

• scripts/main.py：唯一 CLI 入口
• scripts/cli/：参数解析与命令分发
• scripts/db/：SQLite 或本地持久化层
• scripts/service/：业务用例与外部交互
• scripts/util/：通用工具、常量、日志、路径
• scripts/jiangchang_skill_core/：运行时与统一日志副本

数据路径

推荐：

{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/

数据库文件建议：

{...}/{skill_slug}.db

测试时的运行时隔离

本模板的 tests/_support.IsolatedDataRoot 会在测试期间同时设置：

• CLAW_DATA_ROOT / JIANGCHANG_DATA_ROOT → 临时 tempfile 目录
• CLAW_USER_ID / JIANGCHANG_USER_ID → _test

退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。

详见 references/TESTING.md 第 3 节。

编码与输出

• Windows 终端建议在 scripts/main.py 里做 UTF-8 stdout/stderr 包装
• 机读输出优先单行 JSON
• 错误前缀建议统一 ERROR: