chendelian
f973208fe3
All checks were successful
skill-release-placeholder / release (push) Successful in 1s
68 lines
3.2 KiB
Markdown
68 lines
3.2 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/...
|
||
```
|
||
|
||
编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。
|
||
|
||
### `JIANGCHANG_SKILLS_ROOT`（可选）
|
||
|
||
与 `CLAW_SKILLS_ROOT` 同义；匠厂桌面宿主可只注入此名。未设置时，技能可从「本技能 `scripts/` 的上一级目录的上一级」推断并列根（OpenClaw 开发仓与 `skills/<slug>/` 解压布局均适用）。
|
||
|
||
### `JIANGCHANG_APP_ROOT`（可选）
|
||
|
||
匠厂应用安装根。未设置且未设置上述技能根时，Windows 下会尝试用默认 `D:\AI\jiangchang`：若存在子目录 `skills` 且其下像并列技能安装，则技能根为 `{APP}/skills`；否则若 `{APP}` 下直接可见各技能 slug 子目录，则 `{APP}` 即技能根。其他平台默认回退为 `~/.openclaw/skills`。
|
||
|
||
### 加密发布包布局
|
||
|
||
CI 产物 ZIP 解压后与仓库技能目录结构一致：含 `SKILL.md` 与 **`scripts/`**（PyArmor 输出在 `scripts/` 内）。宿主启动入口应为 **`python scripts/main.py`**（工作目录为技能根）。
|
||
|
||
## 本技能推荐的数据目录
|
||
|
||
```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` 注释示例）。**不要在业务模块中散落多套变量名判断。**
|