# 运行时契约（环境变量与目录）

本文档定义技能进程**建议依赖**的外部条件，便于不同 Claw 宿主统一接入。业务技能应**读取环境变量**，而不是在代码里写死路径或用户名。

## 必需程度说明

- **强烈建议**：生产环境由宿主注入；技能应对缺失给出明确错误提示，避免静默写到意外目录。
- **可选**：没有时技能仍可部分运行（例如只读 `health`）。

## 变量一览

### `CLAW_DATA_ROOT`（强烈建议）

用户数据根。多个技能、多个用户的数据都在此根之下分区。

- 典型场景：组织策略指定的盘符路径或 `~/.your-org-data`。
- 未设置时：技能**不应**猜测网络盘；开发机 fallback 仅限 `optional/paths_snippet.py` 中说明的情形。

### `CLAW_USER_ID`（强烈建议）

当前会话所代表的用户或工作空间 ID（字符串）。与数据隔离强相关。

- 用于拼接：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/`
- 未设置时：可用匿名占位（如 `_anon`）**仅用于开发**，生产应显式注入。

### `CLAW_SKILLS_ROOT`（可选）

多个技能以并列目录安装时的根路径，例如：

```text
{CLAW_SKILLS_ROOT}/skill-a/scripts/...
{CLAW_SKILLS_ROOT}/skill-b/scripts/...
```

编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。

## 本技能推荐的数据目录

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

- `skill_slug`：与 `SKILL.md` 内 `metadata.skill.slug` 一致。
- 在此目录下可放置 SQLite 文件、缓存、上传临时文件等；**不要**向版本库提交该目录内容。

## 标准输出约定（建议）

为便于宿主与自动化解析，建议：

- 致命错误：单行前缀 `ERROR:`，例如 `ERROR:MISSING_ENV_CLAW_DATA_ROOT`
- 成功：人类可读一行或多行；若有机读需求，可用 `JSON` 单行输出并在 `SKILL.md` 中说明格式。

## 与具体宿主的关系

若某宿主文档规定了另一套变量名，应在**宿主启动技能子进程时**注入为本文档中的 `CLAW_*` 名称，或在技能内使用一层极薄的 `getenv` 封装（见 `optional/paths_snippet.py` 注释示例）。**不要在业务模块中散落多套变量名判断。**