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

layerfs-sdk-observe

GitHub

用于观察、测量和排查 LayerFS 运行状态，通过调用跟踪、存储指标和守护进程日志进行诊断，不修改项目代码。

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

Trigger Scenarios

LayerFS 运行性能分析与故障排查查看 SDK 调用耗时与阶段分解检查存储去重压缩情况获取守护进程日志与工作区状态

Install

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

More Options

Non-standard path

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

Use without installing

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.

Version History

35d3657 Current 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