56 lines
2.3 KiB
Markdown
56 lines
2.3 KiB
Markdown
# 运行时契约（环境变量与目录）
|
||
|
||
本文档定义技能进程**建议依赖**的外部条件，便于不同 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` 注释示例）。**不要在业务模块中散落多套变量名判断。**
|