# 运行时约定

## 目录结构

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

- `assets/`
- `references/`
- `scripts/`
- `tests/`
- `evals/`

## `scripts/` 分层

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

## 数据路径

推荐：

```text
{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
```

数据库文件建议：

```text
{...}/{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:`