Agent Skills › Ephemeral-AI-Lab/layerfs › layerfs-sdk-observe

layerfs-sdk-observe

GitHub

用于观察、测量和故障排查 LayerFS 运行状态，而非执行实际工作。通过调用 trace、存储指标、后台方法及守护进程日志等内部接口收集诊断数据，辅助维护者分析性能与系统行为。

.agents/skills/layerfs-sdk-observe/SKILL.md Ephemeral-AI-Lab/layerfs

触发场景

需要观察或测量 LayerFS 运行过程进行 LayerFS 运行时故障排查查询 SDK 调用耗时或阶段分解检查存储去重压缩历史获取 Daemon 日志或后端状态

安装

npx skills add Ephemeral-AI-Lab/layerfs --skill layerfs-sdk-observe -g -y

更多选项

非标准路径

npx skills add https://github.com/Ephemeral-AI-Lab/layerfs/tree/main/.agents/skills/layerfs-sdk-observe -g -y

不安装直接使用

npx skills use Ephemeral-AI-Lab/layerfs@layerfs-sdk-observe

指定 Agent (Claude Code)

npx skills add Ephemeral-AI-Lab/layerfs --skill layerfs-sdk-observe -a claude-code -g -y

安装 repo 全部 skill

npx skills add Ephemeral-AI-Lab/layerfs --all -g -y

预览 repo 内 skill

npx skills add Ephemeral-AI-Lab/layerfs --list

SKILL.md

Frontmatter

{
    "name": "layerfs-sdk-observe",
    "description": "Use when observing, measuring or troubleshooting a LayerFS run rather than doing the work itself. Activates on the LayerFS call trace (`LAYERFS_TRACE`, `LAYERFS_TRACE_STEP`), SDK operation timing and phase breakdowns, LayerFS storage deduplication and compression over history, `@layerfs\/backend` (`store.project.get_storage`, `store.branch.list_commit_storage`, `store.fs.list_revisions`, `daemon.workspace.status`, `daemon.workspace.get_storage`, `daemon.process.*`, `daemon.sandbox.get_log`), or LayerFS daemon logs and observation records."
}

Observing a LayerFS run

Status: Current general guide. For whoever watches or troubleshoots a LayerFS run (an orchestrator, a maintainer), not for an agent doing the work. Using the SDK is the separate layerfs-js-sdk skill.

This skill uses internal surfaces: the @layerfs/backend package, the opt-in call trace and the daemon's diagnostic records. None of them changes the project. Don't hand them to an agent doing production work.

Question	Source	Page
How long did each SDK call take, and which phase was slow?	Call trace (`LAYERFS_TRACE`) with phase timing	tracing
Is storage deduplicating and compressing over a long history, or blowing up?	`backend.store.project.get_storage`, `backend.store.branch.list_commit_storage`, trace `sizes`	storage metrics
What did the Store, SQLite, locks and FUSE do during a call?	Daemon records from `backend.daemon.sandbox.get_log` (or `docker logs`), decoded and joined to the trace	daemon logs
Is a Workspace behind its Branch, what does it hold uncommitted, what is a file's history, which background processes run?	Backend methods	backend

Collecting a run

For an agent run you want to analyse afterwards:

Before the run, set LAYERFS_TRACE=<run>/trace.jsonl for every process. Ask the agent to set LAYERFS_TRACE_STEP on each command it runs.
Record identities: LayerFS commit, daemon binary, runtime image digest, addon build.
Snapshot backend.store.project.get_storage() at the start, every N Commits if you can, and at the end.
After the run, while its Sandboxes still run (each closes itself two minutes after its last Workspace is unmounted): page backend.store.branch.list_commit_storage(branch) for every Branch, and save each Sandbox's daemon log with backend.daemon.sandbox.get_log(sandbox, { lines: 2000 }) (see daemon logs).
Decode and join: see daemon logs. Build the per-step table: see storage metrics.

Treat every number as diagnostic: one run, tracing on, no cache control. It is not a benchmark measurement.

版本历史

35d3657 当前 2026-11-02 09:55
从 @layerfs/sdk/operator 迁移至 @layerfs/backend 包；API 命名更新（如 operator.md 改为 backend.md）；引入 Sandbox 相关方法并移除部分旧接口；Daemon 日志获取方式调整为使用 get_log 而非直接 docker logs。
16e622e 2026-10-18 16:12